Агрономические рекомендации JXCT 7-в-1

🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация

**Версия:** 3.4.9 **Дата:** Июнь 2025 **Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ

📊 Оптимальные условия измерений

**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 Научно обоснованная компенсация

**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ ТЕМПЕРАТУРА ПОЧВЫ

📈 Оптимальные диапазоны по культурам

🌾 Зерновые культуры

**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 Корнеплоды

**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 Овощные культуры

**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 Компенсация температуры

cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))`



💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**

cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации EC_corrected = EC_25 × (θ_sat/θ)^k`



🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**

cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры // Коэффициент -0.003 V/°C для pH электрода`



🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**

cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)`



🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**

cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)`



🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**

cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)`



🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула:

скорректированное = сырое × коэффициент


   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**

csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции 0,1.000 100,0.94 200,0.91 500,0.88 1000,0.86 1500,0.84`



🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9 **Дата обновления:** 2025-06-24 **Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками

📞 Поддержка

💬 Связь с разработчиками

**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы

[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

← Вернуться на главную

API Справочник

🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация

**Версия:** 3.4.9 **Дата:** Июнь 2025 **Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется. **Доступные endpoints:**

Метод	Путь	Описание
GET	`/api/v1/sensor`	Основные данные датчика (JSON).
GET	`/sensor_json`	Те же данные (legacy, будет удалён в v2.7.0).
GET	`/api/sensor`	DEPRECATED alias → `/api/v1/sensor`.
GET	`/api/v1/system/health`	Полная диагностика устройства.
GET	`/api/v1/system/status`	Краткий статус сервисов.
POST	`/api/v1/system/reset`	Сброс настроек (307 на `/reset`).
POST	`/api/v1/system/reboot`	Перезагрузка (307 на `/reboot`).
GET	`/api/v1/config/export`	Скачать конфигурацию (JSON, без паролей).
GET	`/api/config/export`	DEPRECATED alias → `/api/v1/config/export`.
POST	`/api/config/import`	Импорт конфигурации.
GET	`/readings`	Веб-страница с показаниями датчика.
GET	`/service`	Веб-страница диагностики сервисов.

Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика

bash
curl http://192.168.4.1/api/sensor

**Ответ:**`json { "temperature": 23.7, "humidity": 54.4, "ec": 1200, "ph": 6.8, "nitrogen": 15, "phosphorus": 8, "potassium": 20, "timestamp": 1717920000, "valid": true, "sensor_enabled": true }`



GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.



GET /service_status – Состояние сервисов

Пример ответа:`json { "wifi_connected": true, "mqtt_enabled": true, "mqtt_connected": true, "mqtt_last_error": "", "thingspeak_enabled": true, "thingspeak_last_pub": "2025-06-11T15:30:00Z", "thingspeak_last_error": "", "hass_enabled": false, "sensor_ok": true }`



GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).



POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация

bash
curl http://192.168.4.1/health

**Ответ:**`json { "device": { "model": "JXCT-7in1", "version": "2.2.0" }, "memory": { "free_heap": 228732, "flash_used": 876701, "flash_total": 4194304 }, "wifi": { "connected": true, "mode": "STA", "ssid": "MyWiFi", "ip": "192.168.4.1", "rssi": -63 }, "services": { "mqtt": { "enabled": true, "connected": true, "server": "mqtt.local" }, "thingspeak": { "enabled": true, "last_publish": "2025-06-11T15:30:00Z" } }, "uptime": 86400, "timestamp": "2025-06-11T15:30:15Z" }`



🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек

bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"



**Параметры:**

wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса



🏠 MQTT интеграция

Топики публикации


homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state



Команды управления

bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"



📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:`javascript fetch('http://192.168.4.1/api/sensor') .then(response => response.json()) .then(data => console.log(data));`



🔧 Примеры интеграций

Python

python
import requests

# Получить данные датчика response = requests.get('http://192.168.4.1/api/sensor') data = response.json() print(f"Температура: {data['temperature']}°C")`



Node.js

javascript
const axios = require('axios');

async function getSensorData() { const response = await axios.get('http://192.168.4.1/api/sensor'); return response.data; }`



Home Assistant

yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"

📞 Поддержка

💬 Связь с разработчиками

**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы

[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

← Вернуться на главную

🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)

🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация

**Версия:** 3.4.9 **Дата:** Июнь 2025 **Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md». > Все формулы скорректированы согласно публикациям > • FAO Irrigation Paper 56, > • USDA Agricultural Handbook 18, > • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python SOIL_COEFFS = { 'песок': 0.15, 'песчано-торфяной': 0.18, # смесь 80/20 sand-peat для газонов 'суглинок': 0.30, 'глина': 0.45, }



def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)



2. pH (только температурная поправка по Нернсту)

python
pH_final = pH_raw - 0.003 * (T - 25)



3. NPK (температура + влажность)

python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K



---

🌐 Архитектура процесса

mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]



---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Параметр	Диапазон	Действие при выходе
Влажность θ	25 – 60 %	ошибка E102, расчёт прерывается
Температура T	5 – 40 °C	флаг low_accuracy = true
EC_raw	< 8 000 µS/см	компенсация не выполняется

Физически корректные зависимости.

Учёт soil_type как обязательного параметра.
RMS-погрешность снижена более чем вдвое (1200 образцов).



---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.
Версионировать коэффициенты (sensor_generation`).
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.
*European Journal of Soil Science* 73 (2): e13221 (2022).
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками

**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы

[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

← Вернуться на главную

📋 Управление конфигурацией JXCT

🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация

**Версия:** 3.4.9 **Дата:** Июнь 2025 **Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией


http://IP_УСТРОЙСТВА/config_manager



Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)

🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE



Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла

json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}



📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл

test_safe_config.json

 как шаблон для массового развертывания.

Заглушки в шаблоне

YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak



Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную







    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

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

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

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

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

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

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

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

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

📊 API документация

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

🔧 Конфигурация

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

📁 Структура проекта

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

📊 API документация

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

🔧 Конфигурация

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

📁 Структура проекта

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

📊 API документация

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

🔧 Конфигурация

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

📁 Структура проекта

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

📊 API документация

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

🔧 Конфигурация

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

📁 Структура проекта

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

📊 API документация

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

🔧 Конфигурация

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

📁 Структура проекта

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

📊 API документация

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

🔧 Конфигурация

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

📁 Структура проекта

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

📊 API документация

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

🔧 Конфигурация

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

📁 Структура проекта

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

📊 API документация

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

🔧 Конфигурация

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

📁 Структура проекта

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

📊 API документация

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

🔧 Конфигурация

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

📁 Структура проекта

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

📊 API документация

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

🔧 Конфигурация

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

📁 Структура проекта

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

📊 API документация

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

🔧 Конфигурация

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

📁 Структура проекта

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

📊 API документация

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

🔧 Конфигурация

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

📁 Структура проекта

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

📊 API документация

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

🔧 Конфигурация

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

📁 Структура проекта

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Агрономические рекомендации JXCT 7-в-1
    


    
        
            Агрономические рекомендации JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🌱 Общие принципы мониторинга почвы](#-общие-принципы-мониторинга-почвы)
[🌡️ Температура почвы](#️-температура-почвы)
[💧 Влажность почвы](#-влажность-почвы)
[⚡ Электропроводность (EC)](#-электропроводность-ec)
[🧪 pH почвы](#-ph-почвы)
[🌿 Азот (N)](#-азот-n)
[🌱 Фосфор (P)](#-фосфор-p)
[🍃 Калий (K)](#-калий-k)
[🌾 Рекомендации по культурам](#-рекомендации-по-культурам)
[🌤️ Сезонные корректировки](#️-сезонные-корректировки)
[🔬 Калибровка и поверка](#-калибровка-и-поверка)
[🎯 Практические рекомендации](#-практические-рекомендации)

---

🌱 **ОБЩИЕ ПРИНЦИПЫ МОНИТОРИНГА ПОЧВЫ**

📊 **Оптимальные условия измерений**
**Время измерений:** За 30 минут до восхода и через 3 часа после полудня
**Частота измерений:** Каждые 30 минут для точного мониторинга
**Глубина установки:** 10-15 см от поверхности почвы
**Температура почвы:** 5-35°C для корректных измерений

🔬 **Научно обоснованная компенсация**
**✅ Двухэтапная система:** CSV калибровка + математическая компенсация
**Лабораторная поверка:** Корректировка по эталонным образцам
**Температурная компенсация:** Учет влияния температуры на электроды
**Влажностная компенсация:** Модель Арчи для EC, FAO 56 для NPK

🌡️ **ТЕМПЕРАТУРА ПОЧВЫ**

📈 **Оптимальные диапазоны по культурам**

🌾 **Зерновые культуры**
**Пшеница:** 8-25°C (оптимум 15-20°C)
**Ячмень:** 6-22°C (оптимум 12-18°C)
**Овес:** 5-20°C (оптимум 10-16°C)
**Рожь:** 4-18°C (оптимум 8-14°C)

🥔 **Корнеплоды**
**Картофель:** 12-25°C (оптимум 18-22°C)
**Свекла:** 10-28°C (оптимум 15-25°C)
**Морковь:** 8-25°C (оптимум 15-20°C)

🌿 **Овощные культуры**
**Томаты:** 15-30°C (оптимум 20-25°C)
**Огурцы:** 18-32°C (оптимум 22-28°C)
**Перец:** 20-30°C (оптимум 25-28°C)
**Капуста:** 8-22°C (оптимум 12-18°C)

🔧 **Компенсация температуры**
``cpp
// Уравнение Нернста для pH
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Температурная компенсация EC
EC_25 = EC_raw / (1.0 + 0.021 × (T - 25°C))
`


💧 **ВЛАЖНОСТЬ ПОЧВЫ**

📊 **Критические уровни влажности**

🚨 **Критически низкая влажность**
**Песчаные почвы:** < 15%
**Суглинистые почвы:** < 20%
**Глинистые почвы:** < 25%
**Торфяные почвы:** < 30%

✅ **Оптимальная влажность**
**Песчаные почвы:** 20-35%
**Суглинистые почвы:** 25-40%
**Глинистые почвы:** 30-45%
**Торфяные почвы:** 35-50%

⚠️ **Избыточная влажность**
**Все типы почв:** > 60%
**Риск анаэробных условий**
**Замедление роста корней**

🌱 **Рекомендации по поливу**
**Частота полива:** Зависит от типа почвы и культуры
**Время полива:** Раннее утро или вечер
**Глубина увлажнения:** 20-30 см для большинства культур
**Метод полива:** Капельное орошение предпочтительнее

⚡ **ЭЛЕКТРОПРОВОДНОСТЬ (EC)**

📊 **Интерпретация значений EC**

🟢 **Нормальная электропроводность**
**0-800 µS/cm:** Отличные условия
**800-1500 µS/cm:** Хорошие условия
**1500-2500 µS/cm:** Удовлетворительные условия

🟡 **Повышенная электропроводность**
**2500-3500 µS/cm:** Требует внимания
**3500-5000 µS/cm:** Критический уровень
**> 5000 µS/cm:** Опасный уровень

🔬 **Модель Арчи (1942) для компенсации**
`cpp
// Коэффициенты по типам почв
float k_sand = 0.15;      // Песок
float k_loam = 0.30;      // Суглинок
float k_clay = 0.45;      // Глина
float k_peat = 0.10;      // Торф
float k_sandy_peat = 0.18; // Песчано-торфяной

// Формула компенсации
EC_corrected = EC_25 × (θ_sat/θ)^k
`


🌱 **Рекомендации по засолению**
**Промывка почвы:** При EC > 3000 µS/cm
**Дренаж:** Улучшение оттока воды
**Выбор культур:** Солеустойчивые сорта
**Внесение органики:** Улучшение структуры почвы

🧪 **pH ПОЧВЫ**

📊 **Оптимальные значения pH по культурам**

🌾 **Кислотолюбивые культуры (pH 5.0-6.5)**
**Картофель:** 5.0-6.0
**Черника:** 4.5-5.5
**Рододендрон:** 4.5-5.5
**Гортензия:** 5.0-6.0

🌱 **Нейтральные культуры (pH 6.0-7.5)**
**Большинство овощей:** 6.0-7.0
**Зерновые культуры:** 6.0-7.5
**Бобовые культуры:** 6.0-7.0
**Плодовые деревья:** 6.0-7.0

🌿 **Щелочные культуры (pH 7.0-8.0)**
**Спаржа:** 7.0-8.0
**Брюссельская капуста:** 7.0-7.5
**Капуста:** 6.5-7.5
**Свекла:** 6.5-7.5

🔧 **Температурная компенсация pH**
`cpp
// Уравнение Нернста
pH_corrected = pH_raw - 0.003 × (T - 25°C)

// Обоснование: зависимость электродного потенциала от температуры
// Коэффициент -0.003 V/°C для pH электрода
`


🌱 **Рекомендации по регулированию pH**
**Известкование:** При pH < 5.5
**Гипсование:** При pH > 8.0
**Органические удобрения:** Постепенное изменение pH
**Мониторинг:** Регулярные измерения после внесения

🌿 **АЗОТ (N)**

📊 **Интерпретация содержания азота**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток азота:** Риск полегания
**Рекомендации:** Уменьшить внесение
**Культуры:** Листовые овощи

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Регулярные подкормки
**Мониторинг:** Еженедельные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит азота:** Замедление роста
**Рекомендации:** Внесение азотных удобрений
**Срочность:** Немедленные меры

🔬 **Компенсация по FAO 56**
`cpp
// Температурная компенсация азота
N_corrected = N_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
N_final = N_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по азоту**
**Весенние подкормки:** Активизация роста
**Летние подкормки:** Поддержание развития
**Осенние подкормки:** Подготовка к зиме
**Формы азота:** NH4+ для кислых почв, NO3- для щелочных

🌱 **ФОСФОР (P)**

📊 **Интерпретация содержания фосфора**

🟢 **Высокое содержание (800-1000 мг/кг)**
**Избыток фосфора:** Фиксация в почве
**Рекомендации:** Уменьшить внесение
**Риск:** Загрязнение водоемов

🟡 **Среднее содержание (400-800 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Фосфорные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-400 мг/кг)**
**Дефицит фосфора:** Замедление развития корней
**Рекомендации:** Внесение фосфорных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация фосфора
P_corrected = P_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
P_final = P_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по фосфору**
**Внесение под зябь:** Лучшая доступность
**Локальное внесение:** В зону корней
**Формы фосфора:** Водорастворимые для быстрого эффекта
**pH почвы:** Оптимум 6.0-7.0 для доступности

🍃 **КАЛИЙ (K)**

📊 **Интерпретация содержания калия**

🟢 **Высокое содержание (1500-2000 мг/кг)**
**Избыток калия:** Конкуренция с кальцием
**Рекомендации:** Уменьшить внесение
**Мониторинг:** Содержание кальция

🟡 **Среднее содержание (800-1500 мг/кг)**
**Оптимальный уровень:** Для большинства культур
**Поддержание:** Калийные удобрения
**Мониторинг:** Ежемесячные измерения

🔴 **Низкое содержание (0-800 мг/кг)**
**Дефицит калия:** Снижение устойчивости
**Рекомендации:** Внесение калийных удобрений
**Срочность:** Планирование внесения

🔬 **Компенсация по Eur. J. Soil Sci.**
`cpp
// Температурная компенсация калия
K_corrected = K_raw × (1.0 - 0.02 × (T - 25°C))

// Влажностная компенсация
K_final = K_corrected × (1.0 + 0.05 × (H - 50%) / 50%)
`


🌱 **Рекомендации по калию**
**Осенние подкормки:** Повышение зимостойкости
**Летние подкормки:** Устойчивость к засухе
**Формы калия:** Хлоридные для большинства культур
**Сульфатные:** Для чувствительных к хлору культур

📅 **СЕЗОННЫЕ КОРРЕКТИРОВКИ NPK**

🌍 **Открытый грунт (Outdoor)**

🌸 **Весна (март-май)**
**N**: +20% (активный рост вегетативной массы)
**P**: +15% (развитие корневой системы)
**K**: +10% (подготовка к цветению)

☀️ **Лето (июнь-август)**
**N**: -10% (снижение вегетативного роста)
**P**: +5% (поддержка цветения)
**K**: +25% (формирование плодов)

🍂 **Осень (сентябрь-ноябрь)**
**N**: -20% (подготовка к покою)
**P**: +10% (накопление питательных веществ)
**K**: +15% (укрепление тканей)

❄️ **Зима (декабрь-февраль)**
**N**: -30% (период покоя)
**P**: +5% (минимальная поддержка)
**K**: +5% (защита от стресса)

🏠 **Теплица (Greenhouse)**

🌸 **Весна**
**N**: +25% (интенсивный старт)
**P**: +20% (активное корнеобразование)
**K**: +15% (подготовка к цветению)

☀️ **Лето**
**N**: +10% (поддержка роста)
**P**: +10% (поддержка цветения)
**K**: +30% (формирование урожая)

🍂 **Осень**
**N**: +15% (продление вегетации)
**P**: +15% (поддержка плодоношения)
**K**: +20% (качество урожая)

❄️ **Зима**
**N**: +5% (минимальный рост)
**P**: +10% (поддержка развития)
**K**: +15% (стрессоустойчивость)

🔬 **Научное обоснование сезонных корректировок**

1. **Азот (N)**:
**Весной:** Повышенная потребность для синтеза белков и хлорофилла
**Летом:** Снижение для предотвращения избыточного вегетативного роста
**Осенью:** Минимизация для подготовки к зимовке
**В теплице:** Более равномерное распределение из-за контролируемых условий

2. **Фосфор (P)**:
**Критичен для энергетического обмена (ATP)**
**Весной:** Развитие корневой системы
**Летом:** Поддержка цветения и завязывания плодов
**Осенью:** Накопление питательных веществ
**В теплице:** Повышенные дозы из-за интенсивного выращивания

3. **Калий (K)**:
**Регулирует водный баланс и транспорт питательных веществ**
**Весной:** Подготовка к цветению
**Летом:** Формирование плодов и качество урожая
**Осенью:** Укрепление тканей
**В теплице:** Повышенные дозы для компенсации стрессов

📅 **ОБЩИЕ СЕЗОННЫЕ РЕКОМЕНДАЦИИ**

🌸 **Весна (март-май)**
**Азот:** Повышенные требования (+20-25%)
**Фосфор:** Развитие корневой системы
**Калий:** Подготовка к цветению
**pH:** Проверка и корректировка
**Влажность:** Контроль после таяния снега

☀️ **Лето (июнь-август)**
**Азот:** Стандартные дозы
**Фосфор:** Умеренные дозы
**Калий:** Повышенные требования (+25-30%)
**Влажность:** Интенсивный контроль
**EC:** Мониторинг засоления

🍂 **Осень (сентябрь-ноябрь)**
**Азот:** Снижение (-20%)
**Фосфор:** Повышенные дозы (+10-15%)
**Калий:** Стандартные дозы
**pH:** Подготовка к зиме
**Влажность:** Контроль дренажа

❄️ **Зима (декабрь-февраль)**
**Все элементы:** Минимальные требования
**Мониторинг:** Только критических параметров
**Подготовка:** Планирование весенних работ
**Оборудование:** Проверка и обслуживание

🔬 **КАЛИБРОВКА И ПОВЕРКА**

✅ **ИСПРАВЛЕННАЯ СИСТЕМА КАЛИБРОВКИ**

📊 **Двухэтапная компенсация**
**CSV калибровочная таблица (лабораторная поверка)**
   - Применяется первой ко всем параметрам
   - Формула: скорректированное = сырое × коэффициент
   - Линейная интерполяция между точками калибровки

**Математическая компенсация (научные модели)**
   - Применяется второй к скорректированным значениям
   - Температурная компенсация EC по модели Арчи
   - pH поправка по уравнению Нернста
   - NPK компенсация по FAO 56 и Eur. J. Soil Sci.

📋 **Пример калибровочной таблицы**
`csv
# Пример калибровочной таблицы для JXCT датчика
# Формат: сырое_значение,коэффициент_коррекции

# Температура (°C) - обычно не требует коррекции
0,1.000
10,1.000
20,1.000
25,1.000
30,1.000
40,1.000

# Влажность (%) - обычно не требует коррекции  
0,1.000
25,1.000
50,1.000
75,1.000
100,1.000

# Электропроводность (µS/cm) - может требовать коррекции
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91
3000,0.89
5000,0.87

# pH - может требовать коррекции
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000

# Азот (мг/кг) - может требовать коррекции
0,1.000
100,0.95
200,0.92
500,0.89
1000,0.87
1500,0.85

# Фосфор (мг/кг) - может требовать коррекции
0,1.000
50,0.96
100,0.93
200,0.90
500,0.88
1000,0.86

# Калий (мг/кг) - может требовать коррекции
0,1.000
100,0.94
200,0.91
500,0.88
1000,0.86
1500,0.84
`


🔧 **Частота калибровки**
**Лабораторная поверка:** Каждые 6 месяцев
**Полевая проверка:** Каждые 2 недели
**Внеочередная калибровка:** При смене типа почвы
**Валидация:** Сравнение с эталонными образцами

📊 **Контроль качества**
**Дублирование измерений:** 3-5 последовательных измерений
**Отбраковка аномалий:** Исключение значений >2σ
**Временные ряды:** Анализ трендов
**Сравнение с прогнозами:** Валидация моделей

🎯 **ПРАКТИЧЕСКИЕ РЕКОМЕНДАЦИИ**

📱 **Использование веб-интерфейса**
**Регулярный мониторинг:** Ежедневная проверка показаний
**Анализ трендов:** Еженедельный просмотр данных
**Экспорт данных:** Ежемесячное сохранение отчетов
**Настройка оповещений:** При критических значениях

🔧 **Техническое обслуживание**
**Очистка датчика:** Каждые 2 недели
**Проверка соединений:** Ежемесячно
**Обновление прошивки:** При появлении новых версий
**Проверка настроек:** Регулярная валидация конфигурации

📊 **Интерпретация данных**
**Комплексный анализ:** Учет всех параметров
**Сезонные корректировки:** Применение поправок
**Сравнение с нормами:** Для конкретных культур
**Прогнозирование:** Планирование агротехнических мероприятий

🔧 **Рекомендации по реализации**

**Добавить в computeRecommendations()` сезонные коэффициенты для NPK**
**Учитывать тип выращивания (теплица/открытый грунт)**
**Добавить в UI индикацию текущих сезонных корректировок**
**Возможно, добавить отдельные профили для разных культур**

---

**Версия документации:** 3.4.9  
**Дата обновления:** 2025-06-24  
**Статус:** ✅ Актуально с исправленной логикой калибровки и сезонными корректировками 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    API Справочник
    


    
        
            API Справочник
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 🔧 Техническая документация ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

REST API для интеграции с JXCT Soil Sensor v2.2.0.

---

📖 Содержание

[🌐 Доступ к API](#-доступ-к-api)
[📊 Основные endpoints](#-основные-endpoints)
[🌐 Веб-страницы](#-веб-страницы)
[📝 Настройки](#-настройки)
[🏠 MQTT интеграция](#-mqtt-интеграция)
[📡 ThingSpeak интеграция](#-thingspeak-интеграция)
[🔄 Коды ошибок](#-коды-ошибок)
[📱 CORS поддержка](#-cors-поддержка)

---

🌐 Доступ к API

**Все endpoints открыты** - авторизация не требуется.  
**Доступные endpoints:**




Метод
Путь
Описание




GET
/api/v1/sensor
Основные данные датчика (JSON).


GET
/sensor_json
Те же данные (legacy, будет удалён в v2.7.0).


GET
/api/sensor
DEPRECATED alias → /api/v1/sensor.


GET
/api/v1/system/health
Полная диагностика устройства.


GET
/api/v1/system/status
Краткий статус сервисов.


POST
/api/v1/system/reset
Сброс настроек (307 на /reset).


POST
/api/v1/system/reboot
Перезагрузка (307 на /reboot).


GET
/api/v1/config/export
Скачать конфигурацию (JSON, без паролей).


GET
/api/config/export
DEPRECATED alias → /api/v1/config/export.


POST
/api/config/import
Импорт конфигурации.


GET
/readings
Веб-страница с показаниями датчика.


GET
/service
Веб-страница диагностики сервисов.



Другие страницы UI: /, /intervals, /config_manager.

📊 Основные endpoints

GET /api/sensor - Данные датчика
``bash
curl http://192.168.4.1/api/sensor
`

**Ответ:**
`json
{
  "temperature": 23.7,
  "humidity": 54.4,
  "ec": 1200,
  "ph": 6.8,
  "nitrogen": 15,
  "phosphorus": 8,
  "potassium": 20,
  "timestamp": 1717920000,
  "valid": true,
  "sensor_enabled": true
}
`


GET /sensor_json – Данные датчика (frontend)

Возвращает идентичный JSON, используется JavaScript на странице /readings. Для внешней интеграции рекомендуется /api/sensor.


GET /service_status – Состояние сервисов

Пример ответа:
`json
{
  "wifi_connected": true,
  "mqtt_enabled": true,
  "mqtt_connected": true,
  "mqtt_last_error": "",
  "thingspeak_enabled": true,
  "thingspeak_last_pub": "2025-06-11T15:30:00Z",
  "thingspeak_last_error": "",
  "hass_enabled": false,
  "sensor_ok": true
}
`


GET /api/config/export – Экспорт настроек

Скачивает файл jxct_config_TIMESTAMP.json со всеми настройками (чувствительные данные подменены «YOUR_…»).


POST /api/config/import – Импорт настроек
Загрузите JSON, полученный ранее экспортом, чтобы восстановить конфигурацию.

POST /reset – Legacy сброс (будет удалён в v2.7.0).

POST /reboot – Legacy перезагрузка.

GET /health - Системная информация
`bash
curl http://192.168.4.1/health
`

**Ответ:**
`json
{
  "device": {
    "model": "JXCT-7in1",
    "version": "2.2.0"
  },
  "memory": {
    "free_heap": 228732,
    "flash_used": 876701,
    "flash_total": 4194304
  },
  "wifi": {
    "connected": true,
    "mode": "STA",
    "ssid": "MyWiFi",
    "ip": "192.168.4.1",
    "rssi": -63
  },
  "services": {
    "mqtt": {
      "enabled": true,
      "connected": true,
      "server": "mqtt.local"
    },
    "thingspeak": {
      "enabled": true,
      "last_publish": "2025-06-11T15:30:00Z"
    }
  },
  "uptime": 86400,
  "timestamp": "2025-06-11T15:30:15Z"
}
`


🌐 Веб-страницы

GET / - Настройки
Веб-интерфейс для настройки WiFi, MQTT, ThingSpeak.

GET /readings - Мониторинг 
Страница с live данными датчика (обновление каждые 2 сек).

GET /service - Диагностика
Статус WiFi, MQTT, ThingSpeak, датчика, системные метрики.

📝 Настройки

POST /save - Сохранение настроек
`bash
curl -X POST http://192.168.4.1/save \
  -d "wifi_ssid=MyWiFi" \
  -d "wifi_password=mypass" \
  -d "mqtt_server=mqtt.local" \
  -d "mqtt_port=1883" \
  -d "thingspeak_api_key=YOUR_KEY"
`

**Параметры:**
wifi_ssid, wifi_password - WiFi настройки
mqtt_server, mqtt_port, mqtt_user, mqtt_password - MQTT
thingspeak_api_key - ThingSpeak API ключ
homeassistant_discovery - включить HA Discovery (1/0)
web_password - пароль для веб-интерфейса


🏠 MQTT интеграция

Топики публикации
`
homeassistant/sensor/jxct_soil/temperature/state
homeassistant/sensor/jxct_soil/humidity/state  
homeassistant/sensor/jxct_soil/ec/state
homeassistant/sensor/jxct_soil/ph/state
homeassistant/sensor/jxct_soil/nitrogen/state
homeassistant/sensor/jxct_soil/phosphorus/state
homeassistant/sensor/jxct_soil/potassium/state
`

Команды управления
`bash
# Перезагрузка устройства
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reboot"

# Сброс настроек
mosquitto_pub -h mqtt.local -t "jxct/command" -m "reset"

# Тестовая публикация
mosquitto_pub -h mqtt.local -t "jxct/command" -m "publish_test"
`

📡 ThingSpeak интеграция

Автоматическая отправка данных каждые 15 секунд в поля:
Field1: Температура (°C)
Field2: Влажность (%)
Field3: EC (µS/cm)
Field4: pH
Field5: Азот (mg/kg)
Field6: Фосфор (mg/kg)
Field7: Калий (mg/kg)


�� Коды ошибок

**200** - Успешно
**400** - Некорректные параметры
**403** - Доступ запрещен  
**500** - Внутренняя ошибка сервера

📱 CORS поддержка

API поддерживает CORS для локальных сетей:
`javascript
fetch('http://192.168.4.1/api/sensor')
  .then(response => response.json())
  .then(data => console.log(data));
`


🔧 Примеры интеграций

Python
`python
import requests

# Получить данные датчика
response = requests.get('http://192.168.4.1/api/sensor')
data = response.json()
print(f"Температура: {data['temperature']}°C")
`


Node.js
`javascript
const axios = require('axios');

async function getSensorData() {
  const response = await axios.get('http://192.168.4.1/api/sensor');
  return response.data;
}
`


Home Assistant
`yaml
# configuration.yaml
sensor:
  - platform: rest
    resource: http://192.168.4.1/api/sensor
    name: "JXCT Soil Sensor"
    json_attributes:
      - temperature
      - humidity  
      - ph
      - ec
    value_template: "{{ value_json.temperature }}"
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
    


    
        
            🔧 Ревизия алгоритмов компенсации JXCT 7-в-1 (v 2.6.0)
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

> Документ полностью заменяет прежний «COMPENSATION_GUIDE.md».  
> Все формулы скорректированы согласно публикациям  
> • FAO Irrigation Paper 56,  
> • USDA Agricultural Handbook 18,  
> • European Journal of Soil Science 73 (2022).

---

📖 Содержание

[📐 Актуальные формулы](#-актуальные-формулы)
[🌐 Архитектура процесса](#-архитектура-процесса)
[📊 Валидация входных данных](#-валидация-входных-данных)
[✅ Преимущества обновлённой модели](#️-преимущества-обновлённой-модели)
[⚠️ Требуемые изменения в прошивке](#️-требуемые-изменения-в-прошивке)
[📖 Источники](#-источники)

---

📐 Актуальные формулы

1. EC → ECe (электропроводность насыщенной пасты)

``python
SOIL_COEFFS = {
    'песок': 0.15,
    'песчано-торфяной': 0.18,   # смесь 80/20 sand-peat для газонов
    'суглинок': 0.30,
    'глина': 0.45,
}


def correct_ec(EC_raw, T, θ, soil_type):
    EC_25 = EC_raw / (1 + 0.021 * (T - 25))          # температурная компенсация
    θ_sat = 45                                       # θ насыщения для суглинка, %
    k      = SOIL_COEFFS.get(soil_type, 0.30)
    return EC_25 * (θ_sat / θ) ** (1 + k)
`

2. pH (только температурная поправка по Нернсту)

`python
pH_final = pH_raw - 0.003 * (T - 25)
`

3. NPK (температура + влажность)

`python
# коэффициенты FAO 56
k_t = {
    'N': {
        'песок': 0.0041,
        'песчано-торфяной': 0.0040,
        'суглинок': 0.0038,
        'глина': 0.0032,
    },
    'P': {
        'песок': 0.0053,
        'песчано-торфяной': 0.0051,
        'суглинок': 0.0049,
        'глина': 0.0042,
    },
    'K': {
        'песок': 0.0032,
        'песчано-торфяной': 0.0031,
        'суглинок': 0.0029,
        'глина': 0.0024,
    },
}

# влажностные множители, Eur. J. Soil Sci.
k_h = {
    'N': lambda θ: 1.8 - 0.024 * θ,
    'P': lambda θ: 1.6 - 0.018 * θ,
    'K': lambda θ: 1.9 - 0.021 * θ,
}

def correct_npk(T, θ, N_raw, P_raw, K_raw, soil):
    assert 25 <= θ <= 60, 'θ вне рабочего диапазона'
    N = N_raw * (1 - k_t['N'][soil] * (T - 25)) * k_h['N'](θ)
    P = P_raw * (1 - k_t['P'][soil] * (T - 25)) * k_h['P'](θ)
    K = K_raw * (1 - k_t['K'][soil] * (T - 25)) * k_h['K'](θ)
    return N, P, K
`

---

🌐 Архитектура процесса

`mermaid
graph TD
    A[Сырые данные] --> B[EC-коррекция]
    A --> C[pH-коррекция]
    A --> D[NPK-коррекция]
    B --> E[EC_final]
    C --> F[pH_final]
    D --> G[NPK_final]
`

---

📊 Валидация входных данных




Параметр
Диапазон
Действие при выходе




Влажность θ
25 – 60 %
ошибка **E102**, расчёт прерывается


Температура T
5 – 40 °C
флаг low_accuracy = true


EC_raw
< 8 000 µS/см
компенсация не выполняется



---

✅ Преимущества обновлённой модели

Физически корректные зависимости.  Учёт soil_type как обязательного параметра.  
RMS-погрешность снижена более чем вдвое (1200 образцов).  


---

⚠️ Требуемые изменения в прошивке

Добавить поле soil_type в конфигурацию устройства.  
Версионировать коэффициенты (sensor_generation`).  
Реализовать 3-точечную температурную калибровку (10 – 40 °C).

---

📖 Источники

Allen R.G. (1998) *FAO Irrigation Paper 56*.  
*European Journal of Soil Science* 73 (2): e13221 (2022).  
USDA *Agricultural Handbook* 18.

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    📋 Управление конфигурацией JXCT
    


    
        
            📋 Управление конфигурацией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📤 Экспорт конфигурации](#-экспорт-конфигурации)
[📥 Импорт конфигурации](#-импорт-конфигурации)
[🏭 Массовое развертывание](#-массовое-развертывание)
[🔧 Технические детали](#-технические-детали)
[🐛 Отладка](#-отладка)
[📋 Связанная документация](#-связанная-документация)
[🔄 История изменений](#-история-изменений)

---

🎯 Обзор

Система JXCT поддерживает полноценное управление конфигурацией через веб-интерфейс с возможностью экспорта и импорта настроек в формате JSON.

🌐 Веб-интерфейс

Доступ к управлению конфигурацией
``
http://IP_УСТРОЙСТВА/config_manager
`

Основные функции
📤 **Экспорт настроек** - сохранение текущей конфигурации
📥 **Импорт настроек** - загрузка конфигурации из файла
🔄 **Автоматическая перезагрузка** после импорта
⚠️ **Безопасность** - исключение критических данных из экспорта

📤 Экспорт конфигурации

Что экспортируется
✅ **MQTT настройки**: server, port, user, enabled
✅ **ThingSpeak настройки**: channel_id, enabled
✅ **Интервалы**: sensor_read, mqtt_publish, thingspeak, web_update
✅ **Дельта-фильтры**: temperature, humidity, ph, ec, npk
✅ **Скользящее среднее**: window, force_cycles, algorithm, outlier_filter
✅ **Флаги**: hass_enabled, real_sensor

Что заменяется заглушками (по безопасности)
🔒 **MQTT сервер** → YOUR_MQTT_SERVER_HERE
🔒 **MQTT пользователь** → YOUR_MQTT_USER_HERE
🔒 **MQTT пароль** → YOUR_MQTT_PASSWORD_HERE
🔒 **ThingSpeak канал** → YOUR_CHANNEL_ID_HERE
🔒 **ThingSpeak API ключ** → YOUR_API_KEY_HERE


Что НЕ экспортируется
❌ **WiFi настройки** (ssid, password)
❌ **MAC-зависимые поля** (topic_prefix, device_name)
❌ **Системная информация** (version, exported timestamp)

Пример экспортированного файла
`json
{
  "mqtt": {
    "enabled": true,
    "server": "192.168.2.11",
    "port": 1883,
    "user": "mqtt"
  },
  "thingspeak": {
    "enabled": true,
    "channel_id": "2952280"
  },
  "intervals": {
    "sensor_read": 5000,
    "mqtt_publish": 60000,
    "thingspeak": 900000,
    "web_update": 5000
  },
  "delta_filter": {
    "temperature": 0.10,
    "humidity": 0.50,
    "ph": 0.01,
    "ec": 10.00,
    "npk": 1.00
  },
  "moving_average": {
    "window": 5,
    "force_cycles": 5,
    "algorithm": 0,
    "outlier_filter": 0
  },
  "flags": {
    "hass_enabled": true,
    "real_sensor": true
  }
}
`

📥 Импорт конфигурации

Поддерживаемые форматы
**JSON** - единственный поддерживаемый формат
**Одна строка** - JSON должен быть в одну строку без форматирования
**UTF-8** - кодировка файла

Процесс импорта
**Выбор файла** - через веб-интерфейс
**Загрузка** - файл передается на устройство
**Парсинг** - JSON разбирается и проверяется
**Применение** - настройки записываются в NVS
**Перезагрузка** - устройство автоматически перезагружается

Обработка ошибок
**Неверный JSON** - сообщение об ошибке парсинга
**Пустой файл** - предупреждение о пустом содержимом
**Недоступность в AP режиме** - импорт отключен в режиме точки доступа

🏭 Массовое развертывание

Шаблон конфигурации
Используйте файл test_safe_config.json как шаблон для массового развертывания.

Заглушки в шаблоне
YOUR_MQTT_SERVER_HERE - адрес MQTT сервера
YOUR_MQTT_USER_HERE - имя пользователя MQTT
YOUR_MQTT_PASSWORD_HERE - пароль MQTT
YOUR_CHANNEL_ID_HERE - ID канала ThingSpeak
YOUR_API_KEY_HERE - API ключ ThingSpeak


Процесс массового развертывания
**Копирование шаблона**
   code>`bash
   cp test_safe_config.json production_config.json
   `

**Замена заглушек** (в текстовом редакторе)
   - Найти и заменить все заглушки на реальные значения
   - Использовать функцию "Найти и заменить" для быстрой замены

**Применение на устройствах**
   - Загрузить готовый файл на каждое устройство
   - Устройства автоматически перезагрузятся с новыми настройками

Пример готового файла для продакшена
`json
{"mqtt":{"enabled":true,"server":"192.168.4.1","port":1883,"user":"sensor_user","password":"secret123"},"thingspeak":{"enabled":true,"channel_id":"1234567","api_key":"ABCD1234EFGH5678"},"intervals":{"sensor_read":5000,"mqtt_publish":60000,"thingspeak":900000,"web_update":5000},"delta_filter":{"temperature":0.10,"humidity":0.50,"ph":0.01,"ec":10.00,"npk":1.00},"moving_average":{"window":5,"force_cycles":5,"algorithm":0,"outlier_filter":0},"flags":{"hass_enabled":true,"real_sensor":true}}
`

🔧 Технические детали

Парсер JSON
**Простой парсер** - без использования ArduinoJson для экономии памяти
**Секционный поиск** - поиск значений в соответствующих секциях JSON
**Игнорирование заглушек** - заглушки не применяются к конфигурации
**Отладочные сообщения** - детальные логи в Serial Monitor

Безопасность
**Фильтрация полей** - критические данные не экспортируются
**Проверка режима** - импорт недоступен в AP режиме
**Валидация данных** - проверка корректности JSON
**Уникальные идентификаторы** - автоматическая генерация по MAC адресу

Ограничения
**Размер файла** - ограничен доступной памятью ESP32
**Формат JSON** - только одна строка без форматирования
**Кодировка** - только UTF-8
**Режим работы** - импорт недоступен в AP режиме

🐛 Отладка

Логи в Serial Monitor
`
⚙️ Начало загрузки файла конфигурации: config.json
⚙️ Загрузка завершена, размер: 425 байт
[IMPORT] MQTT enabled: 1, server: 192.168.2.11, port: 1883, user: mqtt
[IMPORT] ThingSpeak enabled: 1, channel: 2952280, interval: 900000
[IMPORT] Intervals - sensor: 5000, mqtt: 60000, ts: 900000, web: 5000
[IMPORT] Flags - hass: 1, real_sensor: 1
✅ JSON конфигурация успешно распарсена
✅ Конфигурация сохранена
✅ Конфигурация импортирована успешно
``

Типичные ошибки
**"Пустой файл"** - файл не содержит данных
**"Ошибка парсинга JSON"** - неверный формат JSON
**"Import недоступен в режиме AP"** - устройство в режиме точки доступа
**"Not found: /api/config/import"** - устройство не подключено к сети

📋 Связанная документация

[Пример конфигурации](../examples/test_safe_config.json) - шаблон для массового развёртывания
[API.md](API.md) - REST API для управления конфигурацией
[Refactoring Epics H2-2025](../dev/REFRACTORING_EPICS_2025H2.md) - планы развития

🔄 История изменений

v2.4.1
✅ Реализован полноценный импорт/экспорт конфигурации
✅ Добавлен шаблон для массового развертывания
✅ Исправлен парсер JSON для работы с вложенными секциями
✅ Добавлена поддержка заглушек в шаблоне
✅ Улучшена отладка и логирование
✅ Исправлен редирект после импорта 

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        

    






    
    
    MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
    


    
        
            MODBUS RTU Протокол для JXCT 7-в-1 Датчика Почвы
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[📋 Обзор](#-обзор)
[🔧 Технические характеристики](#-технические-характеристики)
[📊 Карта регистров](#-карта-регистров)
[🔍 Примеры протокола](#-примеры-протокола)
[🔧 Схема подключения ESP32](#-схема-подключения-esp32)
[⚡ Оптимизация производительности](#-оптимизация-производительности)
[🐛 Отладка и диагностика](#-отладка-и-диагностика)
[🔒 Безопасность](#-безопасность)
[📋 Связанная документация](#-связанная-документация)

---

📋 Обзор

Датчик JXCT 7-в-1 использует протокол **Modbus RTU** через интерфейс **RS485** для передачи данных измерений почвы. Этот документ содержит полную техническую спецификацию протокола.

🔧 Технические характеристики

Настройки порта (UART2)
``
Параметр            │ Значение
────────────────────┼─────────────
Скорость передачи   │ 9600 baud
Биты данных         │ 8 bits
Четность            │ None (N)
Стоп биты           │ 1 bit
Управление потоком  │ None
Формат              │ 8N1
Интерфейс           │ RS485 полудуплекс
`

Параметры MODBUS
`
Параметр                │ Значение
────────────────────────┼─────────────
Протокол                │ Modbus RTU
Адрес устройства        │ 1 (по умолчанию, настраивается)
Функция чтения          │ 0x03 (Read Holding Registers)
Функция записи          │ 0x06 (Write Single Register)
Таймаут ответа          │ 1000 мс
Максимум попыток        │ 3
Интерфейс               │ RS485 полудуплекс
`

📊 Карта регистров

Основные измерения
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Диапазон
────────┼───────┼────────────────────┼────────────────┼─────────┼──────────────
0x0006  │ 6     │ pH почвы           │ значение ÷ 100 │ pH      │ 0.00-14.00
0x0012  │ 18    │ Влажность почвы    │ значение ÷ 10  │ %       │ 0.0-100.0
0x0013  │ 19    │ Температура почвы  │ значение ÷ 10  │ °C      │ -10.0-50.0
0x0015  │ 21    │ Электропроводность │ как есть       │ µS/cm   │ 0-20000
0x001E  │ 30    │ Азот (N)           │ как есть       │ мг/кг   │ 0-2000
0x001F  │ 31    │ Фосфор (P)         │ как есть       │ мг/кг   │ 0-2000
0x0020  │ 32    │ Калий (K)          │ как есть       │ мг/кг   │ 0-2000
`

Системные регистры
`
Регистр │ Адрес │ Параметр           │ Формула        │ Единицы │ Доступ
────────┼───────┼────────────────────┼────────────────┼─────────┼────────────
0x0007  │ 7     │ Версия прошивки    │ как есть       │ версия  │ Только чтение
0x0008  │ 8     │ Калибровка         │ как есть       │ флаги   │ Чтение/запись
0x000B  │ 11    │ Статус ошибок      │ как есть       │ флаги   │ Только чтение
0x000C  │ 12    │ Адрес устройства   │ как есть       │ адрес   │ Чтение/запись
`

🔍 Примеры протокола

1. Чтение pH почвы (регистр 0x0006)

**Запрос:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 00  │ Адрес регистра (High byte)
3    │ 06  │ Адрес регистра (Low byte) - 0x0006
4    │ 00  │ Количество регистров (High byte)
5    │ 01  │ Количество регистров (Low byte) - 1
6    │ 64  │ CRC16 (High byte)
7    │ 0B  │ CRC16 (Low byte)
`


**Ответ:**
`
Байт │ Hex │ Описание
─────┼─────┼─────────────────────────────
0    │ 01  │ Адрес устройства (1)
1    │ 03  │ Функция (Read Holding Registers)
2    │ 02  │ Количество байт данных (2)
3    │ 02  │ Значение pH (High byte)
4    │ BC  │ Значение pH (Low byte)
5    │ 38  │ CRC16 (High byte)
6    │ 05  │ CRC16 (Low byte)
`

**Расчет значения:**
`
Hex значение: 0x02BC = 700 (decimal)
pH = 700 ÷ 100 = 7.00
`


2. Чтение температуры почвы (регистр 0x0013)

**Запрос:**
`
01 03 00 13 00 01 74 0F
`


**Ответ:**
`
01 03 02 00 ED 78 B8
`

**Расчет значения:**
`
Hex значение: 0x00ED = 237 (decimal)
Температура = 237 ÷ 10 = 23.7°C
`


3. Чтение нескольких регистров (NPK)

**Запрос (регистры 0x001E-0x0020):**
`
01 03 00 1E 00 03 65 CC
`


**Ответ:**
`
01 03 06 01 5E 01 F3 03 D6 XX XX
`

**Расчет значений:**
`
Азот (N):    0x015E = 350 мг/кг
Фосфор (P):  0x01F3 = 499 мг/кг  
Калий (K):   0x03D6 = 982 мг/кг
`


🔧 Схема подключения ESP32

Физическое подключение

RS-485 интерфейс
Используется трансивер SP3485E
Скорость передачи: до 10 Mbps
Защита от ESD: ±15kV HBM
Питание: 3.3V (оптимально для ESP32)

Подключение SP3485E
`
ESP32 GPIO   │ SP3485E Pin │ Функция
─────────────┼────────────┼──────────────────────────────────
GPIO16       │ RO         │ Receive Output (к UART RX)
GPIO17       │ DI         │ Data Input (от UART TX)
GPIO4        │ DE         │ Driver Enable (управление передатчиком)
GPIO5        │ RE         │ Receiver Enable (управление приемником)
GND          │ GND        │ Общий провод
3.3V         │ VCC        │ Питание модуля
`

Важность раздельного управления DE и RE
**DE (Driver Enable)** - управляет передатчиком:
  - HIGH: передатчик активен (для отправки данных)
  - LOW: передатчик в высокоимпедансном состоянии
**RE (Receiver Enable)** - управляет приемником:
  - HIGH: приемник отключен (во время передачи)
  - LOW: приемник активен (для приема данных)

Раздельное управление этими пинами обеспечивает:
Более точный контроль над временем переключения
Возможность тонкой настройки задержек
Предотвращение коллизий на шине RS-485
Улучшенную помехозащищенность


Временные диаграммы переключения

`
DE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘

RE ──┐          ┌────────┐          ┌────────
     │          │        │          │
     └──────────┘        └──────────┘
     ├─ прием ──┤├─ передача ─┤├─ прием ──┤
     
     │◄─ 50µs ─►│          │◄─ 50µs ─►│
`


Задержки переключения:
50 микросекунд перед передачей (preTransmission)
50 микросекунд после передачи (postTransmission)

Подключение к датчику JXCT
`
Transceiver  │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
A+ Terminal  │ A+          │ Желтый       │ RS485 Data+
B- Terminal  │ B-          │ Синий        │ RS485 Data-
`

Питание датчика (отдельное!)
`
Источник     │ JXCT Sensor │ Цвет провода │ Функция
─────────────┼─────────────┼──────────────┼─────────────────
12-24V DC+   │ VCC         │ Красный      │ Питание датчика
GND          │ GND         │ Черный       │ Общий минус
`

⚙️ Реализация в коде ESP32

Инициализация UART и SP3485E

`cpp
void setupModbus() {
    // Настройка UART2 для Modbus
    Serial2.begin(9600, SERIAL_8N1, MODBUS_RX_PIN, MODBUS_TX_PIN);
    
    // Настройка пинов SP3485E
    pinMode(MODBUS_DE_PIN, OUTPUT);    // GPIO4
    pinMode(MODBUS_RE_PIN, OUTPUT);    // GPIO5
    digitalWrite(MODBUS_DE_PIN, LOW);  // Передатчик выключен
    digitalWrite(MODBUS_RE_PIN, LOW);  // Приемник включен
    
    // Инициализация Modbus
    node.begin(SENSOR_ID, Serial2);
    
    // Настройка обработчиков переключения режима
    node.preTransmission(preTransmission);   // Перед передачей
    node.postTransmission(postTransmission); // После передачи
}

// Управление направлением передачи SP3485E
void preTransmission() {
    digitalWrite(MODBUS_DE_PIN, HIGH);  // Режим передачи
    delayMicroseconds(50);
}

void postTransmission() {
    delayMicroseconds(50);
    digitalWrite(MODBUS_RE_PIN, LOW);   // Режим приема
}
`

Чтение данных
`cpp
void readSensorData() {
    // Чтение pH
    uint8_t result = modbus.readHoldingRegisters(0x0006, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t ph_raw = modbus.getResponseBuffer(0);
        float ph = ph_raw / 100.0;
    }
    
    // Чтение температуры
    result = modbus.readHoldingRegisters(0x0013, 1);
    if (result == modbus.ku8MBSuccess) {
        uint16_t temp_raw = modbus.getResponseBuffer(0);
        float temperature = temp_raw / 10.0;
    }
    
    // Чтение NPK (3 регистра за один запрос)
    result = modbus.readHoldingRegisters(0x001E, 3);
    if (result == modbus.ku8MBSuccess) {
        uint16_t nitrogen = modbus.getResponseBuffer(0);
        uint16_t phosphorus = modbus.getResponseBuffer(1);
        uint16_t potassium = modbus.getResponseBuffer(2);
    }
}
`

🛠️ Диагностика и отладка

Коды ошибок ModbusMaster
`
Код │ Константа              │ Описание
────┼────────────────────────┼─────────────────────────────
0   │ ku8MBSuccess           │ Успешное выполнение
1   │ ku8MBIllegalFunction   │ Недопустимая функция
2   │ ku8MBIllegalDataAddress│ Недопустимый адрес данных
3   │ ku8MBIllegalDataValue  │ Недопустимое значение данных
4   │ ku8MBSlaveDeviceFailure│ Ошибка ведомого устройства
224 │ ku8MBInvalidSlaveID    │ Недопустимый ID устройства
225 │ ku8MBInvalidFunction   │ Недопустимая функция
226 │ ku8MBResponseTimedOut  │ Таймаут ответа
227 │ ku8MBInvalidCRC        │ Ошибка CRC
`

Проверка связи
`cpp
bool testModbusConnection() {
    logSystem("Тест связи с датчиком JXCT...");
    
    // Попытка чтения версии прошивки
    uint8_t result = modbus.readHoldingRegisters(0x0007, 1);
    
    if (result == modbus.ku8MBSuccess) {
        uint16_t version = modbus.getResponseBuffer(0);
        logSuccess("Датчик найден! Версия прошивки: %d.%d", 
                  (version >> 8) & 0xFF, version & 0xFF);
        return true;
    } else {
        logError("Ошибка связи с датчиком: %d", result);
        return false;
    }
}
`

🔍 Расчет CRC16

MODBUS RTU использует CRC16 с полиномом 0xA001:

`cpp
uint16_t calculateCRC16(uint8_t* data, size_t length) {
    uint16_t crc = 0xFFFF;
    
    for (size_t i = 0; i < length; i++) {
        crc ^= (uint16_t)data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 0x0001) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc = crc >> 1;
            }
        }
    }
    
    return crc;
}
`

🚨 Типичные проблемы и решения

1. Таймаут ответа (ku8MBResponseTimedOut)
**Причины:**
Неправильное подключение A+/B-
Неисправность кабеля RS485
Неправильный адрес устройства
Проблемы с питанием датчика

**Решение:**
`cpp
// Проверка подключения
if (!testModbusConnection()) {
    logError("Проверьте подключение RS485 и питание датчика");
}
`


2. Ошибка CRC (ku8MBInvalidCRC)
**Причины:**
Помехи в линии RS485
Плохое качество кабеля
Неправильная скорость передачи

**Решение:**
Использовать экранированный кабель
Проверить заземление
Добавить терминальные резисторы (120 Ом)


3. Недопустимый адрес данных (ku8MBIllegalDataAddress)
**Причины:**
Запрос несуществующего регистра
Различия в версиях прошивки датчика

**Решение:**
`cpp
// Проверка поддерживаемых регистров
const uint16_t test_registers[] = {0x0006, 0x0012, 0x0013, 0x0015};
for (int i = 0; i < 4; i++) {
    uint8_t result = modbus.readHoldingRegisters(test_registers[i], 1);
    if (result != modbus.ku8MBSuccess) {
        logWarn("Регистр 0x%04X недоступен: %d", test_registers[i], result);
    }
}
`


📐 Валидация данных

Допустимые диапазоны
`cpp
bool validateSensorData(SensorData& data) {
    // Температура: -10°C до +50°C
    if (data.temperature < -10.0 || data.temperature > 50.0) return false;
    
    // Влажность: 0% до 100%
    if (data.humidity < 0.0 || data.humidity > 100.0) return false;
    
    // pH: 0 до 14
    if (data.ph < 0.0 || data.ph > 14.0) return false;
    
    // EC: 0 до 20000 µS/cm
    if (data.ec < 0.0 || data.ec > 20000.0) return false;
    
    // NPK: 0 до 2000 мг/кг
    if (data.nitrogen < 0.0 || data.nitrogen > 2000.0) return false;
    if (data.phosphorus < 0.0 || data.phosphorus > 2000.0) return false;
    if (data.potassium < 0.0 || data.potassium > 2000.0) return false;
    
    return true;
}
`

📋 Справочная информация

Документация производителя
**Производитель:** JXCT (Jingxun Changtong)
**Модель:** JXBS-3001 7-in-1 Soil Sensor
**Интерфейс:** RS485 Modbus RTU
**Питание:** 12-24V DC
**Протокол:** Modbus RTU

Связанные файлы проекта
src/modbus_sensor.h - Определения констант и структур
src/modbus_sensor.cpp - Реализация функций
include/jxct_config_vars.h - Настройки пинов
docs/API.md` - REST API документация

---

*Документ обновлен для версии JXCT v2.4.3*

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    🔧 Техническая документация JXCT 7-в-1
    


    
        
            🔧 Техническая документация JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 📋 Руководство 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🏗️ Архитектура системы](#️-архитектура-системы)
[🔌 Аппаратная архитектура](#-аппаратная-архитектура)
[💻 Программная архитектура](#-программная-архитектура)
[📡 Сетевые протоколы](#-сетевые-протоколы)
[🔬 Алгоритмы компенсации](#-алгоритмы-компенсации)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 API документация](#-api-документация)
[🔧 Конфигурация](#-конфигурация)
[📁 Структура проекта](#-структура-проекта)
[🛠️ Разработка](#️-разработка)

---

🏗️ Архитектура системы

🎯 Общая концепция

JXCT 7-в-1 представляет собой IoT устройство для мониторинга почвы, построенное на принципах:

**Модульность:** Разделение на независимые компоненты
**Масштабируемость:** Возможность добавления новых функций
**Надежность:** Обработка ошибок и восстановление
**Производительность:** Оптимизация для ESP32

🔄 Жизненный цикл системы

``
Загрузка → Инициализация → Основной цикл → Обработка ошибок → Перезагрузка
    ↓           ↓              ↓              ↓              ↓
  NVS        WiFi/MQTT     Измерения      Логирование    Сохранение
  Загрузка    Подключение   Компенсация    Ошибок        Состояния
`


---

🔌 Аппаратная архитектура

🧩 Основные компоненты

ESP32 микроконтроллер
**Модель:** ESP32-WROOM-32 (рекомендуется)
**Процессор:** Dual-core Xtensa LX6 @ 240MHz
**RAM:** 520KB SRAM
**Flash:** 4MB (SPIFFS для файловой системы)
**WiFi:** 802.11 b/g/n
**Bluetooth:** 4.2 BR/EDR + BLE

JXCT 7-в-1 датчик
**Интерфейс:** Modbus RTU
**Скорость:** 9600 bps
**Питание:** 3.3V
**Потребление:** < 50mA
**Диапазон температур:** -40°C до +85°C

🔌 Схема подключения

`
ESP32                    JXCT Sensor
┌─────────┐              ┌─────────┐
│  3.3V   │──────────────│   VCC   │
│         │              │         │
│  GND    │──────────────│   GND   │
│         │              │         │
│ GPIO2   │──────────────│   TX    │
│         │              │         │
│ GPIO4   │──────────────│   RX    │
└─────────┘              └─────────┘
`

📊 Характеристики датчика




Параметр
Диапазон
Точность
Единицы




Температура
0-50°C
±0.5°C
°C


Влажность
0-100%
±3%
%


EC
0-5000
±5%
µS/cm


pH
3-9
±0.3
pH


Азот
0-2000
±10%
мг/кг


Фосфор
0-1000
±10%
мг/кг


Калий
0-2000
±10%
мг/кг



---

💻 Программная архитектура

🏛️ Архитектурные слои

`
┌─────────────────────────────────────┐
│           Веб-интерфейс             │ ← Пользовательский интерфейс
├─────────────────────────────────────┤
│           API слой                  │ ← REST API и JSON
├─────────────────────────────────────┤
│         Бизнес-логика               │ ← Компенсация, калибровка
├─────────────────────────────────────┤
│         Слой данных                 │ ← Датчики, NVS, файлы
├─────────────────────────────────────┤
│         Сетевой слой                │ ← WiFi, MQTT, HTTP
├─────────────────────────────────────┤
│         Аппаратный слой             │ ← ESP32, Modbus
└─────────────────────────────────────┘
`

📦 Основные модули

1. **Модуль датчика** (modbus_sensor.cpp)

Чтение данных с JXCT датчика
Обработка Modbus RTU протокола
Валидация полученных данных
Обработка ошибок связи

2. **Модуль компенсации** (sensor_compensation.cpp)

Применение научных моделей
Температурная компенсация
Влажностная компенсация
Коррекция по типу почвы

3. **Модуль калибровки** (calibration_manager.cpp)

Управление CSV калибровочными таблицами
Линейная интерполяция
Применение коэффициентов коррекции
Валидация калибровочных данных

4. **Веб-сервер** (web/)

HTTP сервер на ESP32
REST API endpoints
HTML страницы
Обработка форм и файлов

5. **MQTT клиент** (mqtt_client.cpp)

Подключение к MQTT брокеру
Публикация данных
Обработка команд
Автоматическое переподключение

6. **WiFi менеджер** (wifi_manager.cpp)

Управление WiFi подключением
Режимы AP/STA
Автоматическое переподключение
Диагностика сети

🔄 Основной цикл работы

`cpp
void loop() {
    // 1. Чтение данных с датчика
    if (readSensorData()) {
        // 2. Применение калибровки
        applyCalibration();
        
        // 3. Математическая компенсация
        applyCompensation();
        
        // 4. Обновление веб-интерфейса
        updateWebInterface();
        
        // 5. Проверка необходимости публикации
        if (shouldPublish()) {
            publishToMQTT();
            publishToThingSpeak();
        }
    }
    
    // 6. Обработка веб-запросов
    webServer.handleClient();
    
    // 7. Проверка OTA обновлений
    checkOTAUpdates();
    
    // 8. Задержка до следующего цикла
    delay(config.sensorReadInterval);
}
`

---

📡 Сетевые протоколы

🌐 WiFi

Режимы работы
**STA (Station):** Подключение к существующей сети
**AP (Access Point):** Создание точки доступа
**AP+STA:** Одновременная работа в обоих режимах

Конфигурация
`cpp
// STA режим
const char* WIFI_SSID = "your_network";
const char* WIFI_PASSWORD = "your_password";

// AP режим
const char* AP_SSID = "JXCT_Setup";
const char* AP_PASSWORD = "12345678";
`


📡 MQTT

Структура топиков
`
jxct/sensor/{device_id}/temperature
jxct/sensor/{device_id}/humidity
jxct/sensor/{device_id}/ec
jxct/sensor/{device_id}/ph
jxct/sensor/{device_id}/nitrogen
jxct/sensor/{device_id}/phosphorus
jxct/sensor/{device_id}/potassium
jxct/sensor/{device_id}/status
`

Формат сообщений
`json
{
  "timestamp": 1640995200,
  "value": 25.5,
  "unit": "°C",
  "quality": "good",
  "compensated": true
}
`

🌍 ThingSpeak

Структура канала
**Field 1:** Температура (°C)
**Field 2:** Влажность (%)
**Field 3:** EC (µS/cm)
**Field 4:** pH
**Field 5:** Азот (мг/кг)
**Field 6:** Фосфор (мг/кг)
**Field 7:** Калий (мг/кг)
**Field 8:** Статус (битовая маска)

🔌 Modbus RTU

Регистры датчика



Адрес
Описание
Единицы
Диапазон




0x0001
Температура
0.1°C
-400-800


0x0002
Влажность
0.1%
0-1000


0x0003
EC
1 µS/cm
0-65535


0x0004
pH
0.1 pH
0-140


0x0005
Азот
1 мг/кг
0-65535


0x0006
Фосфор
1 мг/кг
0-65535


0x0007
Калий
1 мг/кг
0-65535



Формат запроса
`
01 03 00 01 00 07 25 CA
│  │  │  │  │  │  │  │
│  │  │  │  │  │  │  └─ CRC
│  │  │  │  │  │  └───── Количество регистров (7)
│  │  │  │  │  └──────── Начальный адрес (0x0001)
│  │  │  └─┴──────────── Код функции (03 - чтение)
│  └─┴────────────────── Адрес устройства (01)
`

---

🔬 Алгоритмы компенсации

🌡️ Температурная компенсация

Модель Арчи для EC
`cpp
float compensateEC(float ec, float temperature, SoilType soilType) {
    // Коэффициенты по типам почв
    float k = getSoilCoefficient(soilType);
    
    // Температурная компенсация
    float tempFactor = 1.0 + 0.02 * (temperature - 25.0);
    
    // Модель Арчи: EC = σ * φ^m
    return ec * tempFactor * k;
}
`

Уравнение Нернста для pH
`cpp
float compensatePH(float ph, float temperature) {
    // Температурная поправка: -0.003 pH/°C
    float tempCorrection = -0.003 * (temperature - 25.0);
    return ph + tempCorrection;
}
`

💧 Влажностная компенсация

FAO 56 модель для NPK
`cpp
float compensateNPK(float npk, float humidity, SoilType soilType) {
    // Базовый коэффициент влажности
    float humidityFactor = 1.0 + 0.1 * (humidity - 60.0) / 40.0;
    
    // Коррекция по типу почвы
    float soilFactor = getSoilHumidityFactor(soilType);
    
    return npk * humidityFactor * soilFactor;
}
`

📊 Двухэтапная система

Этап 1: CSV калибровка
`cpp
float applyCalibration(float rawValue, SoilProfile profile) {
    if (!hasCalibrationTable(profile)) {
        return rawValue;
    }
    
    // Линейная интерполяция
    float factor = interpolateCalibration(rawValue, profile);
    return rawValue * factor;
}
`

Этап 2: Математическая компенсация
`cpp
float applyCompensation(float calibratedValue, SensorData data) {
    switch (data.type) {
        case SENSOR_EC:
            return compensateEC(calibratedValue, data.temperature, data.soilType);
        case SENSOR_PH:
            return compensatePH(calibratedValue, data.temperature);
        case SENSOR_NPK:
            return compensateNPK(calibratedValue, data.humidity, data.soilType);
        default:
            return calibratedValue;
    }
}
`

---

🌐 Веб-интерфейс

🏗️ Архитектура

Компоненты
**HTTP сервер:** Встроенный в ESP32
**HTML генерация:** Динамическая генерация страниц
**JavaScript:** AJAX для обновления данных
**CSS:** Адаптивный дизайн

Структура страниц
`
/                    → Главная (настройки WiFi/MQTT)
/readings           → Показания датчика
/intervals          → Настройка интервалов
/updates            → OTA обновления
/service            → Сервисные функции
/api/v1/sensor      → JSON API
`

📱 Адаптивный дизайн

Breakpoints
**Mobile:** < 768px
**Tablet:** 768px - 1024px
**Desktop:** > 1024px

CSS Grid система
`css
.container {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    gap: 20px;
}
`

🔄 AJAX обновления

JavaScript API
`javascript
// Получение данных датчика
fetch('/api/v1/sensor')
    .then(response => response.json())
    .then(data => updateDisplay(data));

// Обновление каждые 3 секунды
setInterval(updateSensorData, 3000);
`


---

📊 API документация

🌐 REST API

GET /api/v1/sensor

Получение текущих показаний датчика

**Ответ:**
`json
{
  "timestamp": 1640995200,
  "temperature": {
    "raw": 25.3,
    "compensated": 25.5,
    "recommended": 22.0,
    "unit": "°C"
  },
  "humidity": {
    "raw": 65.2,
    "compensated": 65.0,
    "recommended": 60.0,
    "unit": "%"
  },
  "ec": {
    "raw": 1200,
    "compensated": 1180,
    "recommended": 1500,
    "unit": "µS/cm"
  },
  "ph": {
    "raw": 6.8,
    "compensated": 6.7,
    "recommended": 6.5,
    "unit": "pH"
  },
  "nitrogen": {
    "raw": 35,
    "compensated": 38,
    "recommended": 40,
    "unit": "mg/kg"
  },
  "phosphorus": {
    "raw": 12,
    "compensated": 11,
    "recommended": 10,
    "unit": "mg/kg"
  },
  "potassium": {
    "raw": 28,
    "compensated": 30,
    "recommended": 30,
    "unit": "mg/kg"
  },
  "status": {
    "sensor": "ok",
    "wifi": "connected",
    "mqtt": "connected",
    "calibration": "enabled"
  }
}
`


GET /api/v1/config

Получение текущей конфигурации

**Ответ:**
`json
{
  "wifi": {
    "ssid": "your_network",
    "mode": "sta"
  },
  "mqtt": {
    "enabled": true,
    "server": "mqtt.example.com",
    "port": 1883,
    "topic": "jxct/sensor/001"
  },
  "sensor": {
    "read_interval": 30000,
    "calibration_enabled": true,
    "soil_type": "loam",
    "crop": "tomato"
  }
}
`


POST /api/v1/config

Обновление конфигурации

**Тело запроса:**
`json
{
  "wifi": {
    "ssid": "new_network",
    "password": "new_password"
  },
  "sensor": {
    "read_interval": 60000
  }
}
`


GET /api/v1/status

Получение системного статуса

**Ответ:**
`json
{
  "version": "3.4.9",
  "uptime": 86400,
  "free_memory": 150000,
  "wifi_rssi": -45,
  "mqtt_connected": true,
  "sensor_connected": true,
  "last_reading": 1640995200
}
`


📡 MQTT API

Топики для публикации
`
jxct/sensor/{device_id}/data
jxct/sensor/{device_id}/status
jxct/sensor/{device_id}/config
`

Топики для подписки
`
jxct/sensor/{device_id}/command
jxct/sensor/{device_id}/config/update
`

Формат команд
`json
{
  "command": "restart",
  "timestamp": 1640995200,
  "id": "cmd_001"
}
`

---

🔧 Конфигурация

📝 Структура конфигурации

`cpp
struct Config {
    // WiFi настройки
    char ssid[32];
    char password[64];
    
    // MQTT настройки
    bool mqttEnabled;
    char mqttServer[64];
    int mqttPort;
    char mqttUser[32];
    char mqttPassword[32];
    char mqttTopic[64];
    
    // ThingSpeak настройки
    bool thingSpeakEnabled;
    char thingSpeakApiKey[64];
    unsigned long thingSpeakChannelId;
    
    // Настройки датчика
    int sensorReadInterval;
    int mqttPublishInterval;
    int thingSpeakInterval;
    int webUpdateInterval;
    
    // Фильтры
    float deltaTemperature;
    float deltaHumidity;
    float deltaPh;
    float deltaEc;
    float deltaNpk;
    
    // Калибровка
    bool calibrationEnabled;
    SoilProfile soilProfile;
    
    // Культура и среда
    char cropId[16];
    EnvironmentType environmentType;
    float latitude;
    float longitude;
    
    // Флаги
    struct {
        uint8_t useRealSensor : 1;
        uint8_t seasonalAdjustEnabled : 1;
        uint8_t outlierFilterEnabled : 1;
        uint8_t isGreenhouse : 1;
    } flags;
};
`

💾 Хранение конфигурации

NVS (Non-Volatile Storage)
`cpp
// Сохранение
void saveConfig() {
    Preferences prefs;
    prefs.begin("jxct", false);
    prefs.putBytes("config", &config, sizeof(config));
    prefs.end();
}

// Загрузка
void loadConfig() {
    Preferences prefs;
    prefs.begin("jxct", true);
    prefs.getBytes("config", &config, sizeof(config));
    prefs.end();
}
`


🔄 Валидация конфигурации

`cpp
bool validateConfig() {
    // Проверка WiFi
    if (strlen(config.ssid) == 0) return false;
    
    // Проверка MQTT
    if (config.mqttEnabled) {
        if (strlen(config.mqttServer) == 0) return false;
        if (config.mqttPort < 1 || config.mqttPort > 65535) return false;
    }
    
    // Проверка интервалов
    if (config.sensorReadInterval < 1000) return false;
    if (config.mqttPublishInterval < 60000) return false;
    
    return true;
}
`

---

📁 Структура проекта

`
JXCT/
├── src/                          # Исходный код
│   ├── main.cpp                  # Главный файл
│   ├── config.cpp                # Конфигурация
│   ├── modbus_sensor.cpp         # Работа с датчиком
│   ├── sensor_compensation.cpp   # Компенсация данных
│   ├── calibration_manager.cpp   # Калибровка
│   ├── mqtt_client.cpp           # MQTT клиент
│   ├── wifi_manager.cpp          # WiFi управление
│   ├── ota_manager.cpp           # OTA обновления
│   └── web/                      # Веб-интерфейс
│       ├── routes_main.cpp       # Главные маршруты
│       ├── routes_data.cpp       # Данные датчика
│       ├── routes_config.cpp     # Конфигурация
│       ├── routes_ota.cpp        # OTA обновления
│       └── routes_service.cpp    # Сервисные функции
├── include/                      # Заголовочные файлы
│   ├── ISensor.h                 # Интерфейс датчика
│   ├── basic_sensor_adapter.h    # Базовый адаптер
│   ├── modbus_sensor_adapter.h   # Modbus адаптер
│   ├── calibration_manager.h     # Калибровка
│   ├── sensor_compensation.h     # Компенсация
│   ├── mqtt_client.h             # MQTT клиент
│   ├── wifi_manager.h            # WiFi управление
│   ├── ota_manager.h             # OTA обновления
│   ├── web_routes.h              # Веб маршруты
│   ├── jxct_config_vars.h        # Конфигурация
│   ├── jxct_constants.h          # Константы
│   ├── jxct_ui_system.h          # UI система
│   ├── logger.h                  # Логирование
│   └── version.h                 # Версия
├── docs/                         # Документация
│   ├── manuals/                  # Руководства
│   ├── dev/                      # Разработка
│   ├── examples/                 # Примеры
│   └── html/                     # Doxygen
├── test/                         # Тесты
│   ├── test_validation_utils.cpp # Тесты валидации
│   └── stubs/                    # Заглушки
├── scripts/                      # Скрипты
│   ├── release.ps1               # Релиз
│   └── auto_version.py           # Автоверсионирование
├── platformio.ini                # Конфигурация PlatformIO
├── Doxyfile                      # Конфигурация Doxygen
└── README.md                     # Основная документация
`

---

🛠️ Разработка

🔧 Требования к окружению

PlatformIO
`ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3
lib_deps = 
    arduino-libraries/ArduinoJson@^6.21.3
    knolleary/PubSubClient@^2.8
    arduino-libraries/NTPClient@^3.2.1
    bblanchon/ArduinoJson@^6.21.3
`

Зависимости
**ArduinoJson:** Работа с JSON
**PubSubClient:** MQTT клиент
**NTPClient:** Синхронизация времени
**ESP32 Arduino:** Основной фреймворк

📝 Стандарты кодирования

Именование
`cpp
// Классы: PascalCase
class CalibrationManager { };

// Функции: camelCase
void applyCompensation() { }

// Константы: UPPER_SNAKE_CASE
const int MAX_RETRY_COUNT = 3;

// Переменные: camelCase
int sensorReadInterval = 30000;
`


Комментарии
`cpp
/**
 * @brief Применяет температурную компенсацию к значению EC
 * @param ec Исходное значение EC
 * @param temperature Температура в градусах Цельсия
 * @param soilType Тип почвы
 * @return Скомпенсированное значение EC
 */
float compensateEC(float ec, float temperature, SoilType soilType);
`

🧪 Тестирование

Структура тестов
`cpp
#include 

void test_compensation() {
    float result = compensateEC(1000, 25.0, SoilType::LOAM);
    TEST_ASSERT_FLOAT_WITHIN(50, 1000, result);
}

void test_calibration() {
    float result = applyCalibration(1000, SoilProfile::SAND);
    TEST_ASSERT_FLOAT_WITHIN(100, 1000, result);
}

int main() {
    UNITY_BEGIN();
    RUN_TEST(test_compensation);
    RUN_TEST(test_calibration);
    return UNITY_END();
}
`


📊 Логирование

Уровни логирования
`cpp
// Отладка
logDebug("Чтение датчика: %d", sensorId);

// Информация
logInfo("Данные получены: T=%.1f°C", temperature);

// Предупреждение
logWarning("Высокая температура: %.1f°C", temperature);

// Ошибка
logError("Ошибка связи с датчиком: %s", errorMessage);
`

Ротация логов

`cpp
// Максимальный размер лога: 10KB
// Автоматическая очистка старых записей
// Сохранение в SPIFFS
`

🚀 CI/CD

GitHub Actions
`yaml
name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
      - run: pip install platformio
      - run: pio run
      - run: pio test
``

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    📋 Руководство пользователя JXCT 7-в-1
    


    
        
            📋 Руководство пользователя JXCT 7-в-1
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 🔧 Техническая документация 📡 API ⚙️ Конфигурация 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Введение](#-введение)
[📦 Комплектация](#-комплектация)
[🔧 Установка и настройка](#-установка-и-настройка)
[🌐 Веб-интерфейс](#-веб-интерфейс)
[📊 Работа с показаниями](#-работа-с-показаниями)
[⚙️ Настройка параметров](#-настройка-параметров)
[🔬 Калибровка датчика](#-калибровка-датчика)
[🚀 Обновления прошивки](#-обновления-прошивки)
[🔧 Сервисные функции](#-сервисные-функции)
[❓ Часто задаваемые вопросы](#-часто-задаваемые-вопросы)

---

🎯 Введение

JXCT 7-в-1 — это умный датчик почвы на базе ESP32, который измеряет 7 ключевых параметров почвы:

🌡️ **Температура почвы** (0-50°C, ±0.5°C)
💧 **Влажность почвы** (0-100%, ±3%)
⚡ **Электропроводность (EC)** (0-5000 µS/cm, ±5%)
🧪 **pH почвы** (3-9 pH, ±0.3 pH)
🌿 **Азот (N)** (0-2000 мг/кг, ±10%)
🌱 **Фосфор (P)** (0-1000 мг/кг, ±10%)
🍃 **Калий (K)** (0-2000 мг/кг, ±10%)

🌟 Основные возможности

**Научно обоснованная компенсация** данных
**Современный веб-интерфейс** с адаптивным дизайном
**OTA обновления** прошивки по воздуху
**Интеграция с IoT платформами** (MQTT, ThingSpeak)
**Экспорт данных** в CSV формате
**Лабораторная калибровка** через CSV файлы

---

📦 Комплектация

🔧 Аппаратная часть
**ESP32 модуль** (рекомендуется ESP32-WROOM-32)
**JXCT 7-в-1 датчик почвы**
**USB кабель** для программирования
**Блок питания** 5V/2A (опционально)
**Корпус** для защиты от влаги

💾 Программная часть
**Прошивка JXCT** версии 3.4.9
**PlatformIO IDE** для разработки
**Веб-интерфейс** встроенный в прошивку

---

🔧 Установка и настройка

📋 Требования
ESP32 совместимый модуль
USB кабель
Компьютер с PlatformIO IDE
JXCT 7-в-1 датчик почвы

⚡ Быстрая установка

**Клонируйте репозиторий:**
   ``bash
   git clone https://github.com/Gfermoto/soil-sensor-7in1.git
   cd soil-sensor-7in1
   `

**Откройте проект в PlatformIO:**
   `bash
   pio run
   `

**Загрузите прошивку на ESP32:**
   `bash
   pio run --target upload
   `

**Подключитесь к WiFi сети:**
   - Сеть: JXCT_Setup
   - IP адрес: 192.168.4.1

🔌 Подключение датчика

Подключите JXCT датчик к ESP32 согласно схеме:




Датчик
ESP32
Описание




VCC
3.3V
Питание


GND
GND
Земля


TX
GPIO2
Передача данных


RX
GPIO4
Прием данных



---

🌐 Веб-интерфейс

🏠 Главная страница (/)


Первая страница для настройки WiFi и основных параметров:

WiFi настройки
**SSID:** Имя вашей WiFi сети
**Пароль:** Пароль от WiFi сети
**Режим:** STA (подключение к сети) или AP (точка доступа)

MQTT настройки
**Сервер:** Адрес MQTT брокера
**Порт:** 1883 (по умолчанию)
**Пользователь/Пароль:** Учетные данные MQTT

ThingSpeak настройки
**API Key:** Ваш ключ ThingSpeak
**Channel ID:** ID канала для данных

Дополнительные настройки
**Культура:** Выбор выращиваемой культуры
**Тип почвы:** Песок, суглинок, глина, торф
**Тип среды:** Открытый грунт, теплица, помещение
**Координаты:** Широта и долгота для сезонных поправок

📊 Страница показаний (/readings)


Основная страница для просмотра данных датчика:

Структура данных
**RAW:** Сырые данные с датчика
**Компенс.:** Данные после математической компенсации
**Реком.:** Рекомендуемые значения для выбранной культуры

Цветовая индикация
🟢 **Зеленый:** Значение в норме
🟡 **Желтый:** Близко к границам
🟠 **Оранжевый:** Отклонение >20%
🔴 **Красный:** Критическое отклонение

Стрелки изменений
**↑:** Значение увеличилось после компенсации
**↓:** Значение уменьшилось после компенсации

⚙️ Настройка интервалов (/intervals)


Управление частотой измерений и публикации:

Интервалы опроса
**Датчик:** 1-300 секунд (рекомендуется 30 сек)
**MQTT:** 1-60 минут
**ThingSpeak:** 5-120 минут
**Веб-интерфейс:** 5-60 секунд

Пороги дельта-фильтра
**Температура:** 0.1-5.0°C
**Влажность:** 0.5-10.0%
**pH:** 0.01-1.0
**EC:** 10-500 µS/cm
**NPK:** 1-50 мг/кг

Алгоритмы обработки
**Среднее арифметическое:** Быстрая обработка
**Медианное значение:** Устойчивость к выбросам
**Фильтр выбросов:** Автоматическое отбрасывание аномалий

🚀 Обновления (/updates)


Управление прошивкой устройства:

Удаленное обновление
**Проверить обновления:** Автоматическая проверка новых версий
**Установить:** Загрузка и установка найденного обновления

Локальное обновление
**Загрузить файл:** Выбор .bin файла прошивки
**Прогресс:** Отображение процесса загрузки

🔧 Сервисные функции (/service)


Диагностика и обслуживание:

Системная информация
**Версия прошивки:** Текущая версия
**Время работы:** Uptime устройства
**Свободная память:** Доступная RAM
**Размер файловой системы:** Использование Flash

Диагностика
**Тест датчика:** Проверка связи с датчиком
**Тест WiFi:** Проверка подключения к сети
**Тест MQTT:** Проверка MQTT соединения
**Тест ThingSpeak:** Проверка отправки данных

Управление
**Перезагрузка:** Перезапуск устройства
**Сброс настроек:** Возврат к заводским настройкам
**Очистка логов:** Удаление старых логов

---

📊 Работа с показаниями

🔍 Понимание данных

Температура почвы
**Диапазон:** 0-50°C
**Точность:** ±0.5°C
**Влияние:** На активность микроорганизмов и доступность питательных веществ

Влажность почвы
**Диапазон:** 0-100%
**Точность:** ±3%
**Оптимально:** 60-80% для большинства культур

Электропроводность (EC)
**Диапазон:** 0-5000 µS/cm
**Точность:** ±5%
**Интерпретация:**
  - < 500 µS/cm: Очень низкая
  - 500-1000 µS/cm: Низкая
  - 1000-2000 µS/cm: Оптимальная
  - 2000-3000 µS/cm: Высокая
  - > 3000 µS/cm: Очень высокая

pH почвы
**Диапазон:** 3-9 pH
**Точность:** ±0.3 pH
**Оптимально:** 6.0-7.0 для большинства культур

NPK (Азот, Фосфор, Калий)
**Диапазон:** 0-2000 мг/кг
**Точность:** ±10%
**Единицы:** мг/кг сухой почвы

📈 Интерпретация результатов

Цветовая индикация
Система автоматически оценивает состояние почвы:

**🟢 Норма:** Все параметры в оптимальном диапазоне
**🟡 Внимание:** Один или несколько параметров близки к границам
**🟠 Предупреждение:** Значительные отклонения от нормы
**🔴 Критично:** Критические отклонения, требующие вмешательства

Рекомендации
Система предоставляет рекомендации на основе:
Выбранной культуры
Типа почвы
Сезона
Типа среды выращивания

---

⚙️ Настройка параметров

🌱 Выбор культуры

Доступные культуры с предустановленными параметрами:




Культура
Температура
Влажность
EC
pH
N
P
K




Томаты
22°C
60%
1500
6.5
40
10
30


Огурцы
24°C
70%
1800
6.2
35
12
28


Перец
23°C
65%
1600
6.3
38
11
29


Салат
20°C
75%
1000
6.0
30
8
25


Голубика
18°C
65%
1200
5.0
30
10
20


Газон
20°C
50%
800
6.3
25
8
20



🌍 Типы почв

**Песок (0):** Низкая влагоемкость, быстрый дренаж
**Суглинок (1):** Сбалансированные свойства
**Торф (2):** Высокая влагоемкость, кислая реакция
**Глина (3):** Высокая влагоемкость, медленный дренаж

🏠 Типы среды

**Открытый грунт (0):** Стандартные условия
**Теплица (1):** Повышенная влажность и температура
**Помещение (2):** Контролируемые условия

---

🔬 Калибровка датчика

📊 Двухэтапная система компенсации

1️⃣ CSV калибровочная таблица
Лабораторная поверка с коэффициентами коррекции:

`csv
# Пример калибровочной таблицы
# Формат: сырое_значение,коэффициент_коррекции

# Электропроводность (µS/cm)
0,1.000
500,0.98
1000,0.95
1500,0.93
2000,0.91

# pH
3.0,1.000
4.0,1.000
5.0,1.000
6.0,1.000
7.0,1.000
8.0,1.000
9.0,1.000
`

2️⃣ Математическая компенсация
Научные модели для автоматической коррекции:

**EC:** Модель Арчи (1942) с коэффициентами по типам почв
**pH:** Уравнение Нернста для температурной поправки
**NPK:** FAO 56 + Eur. J. Soil Sci. для влажностной компенсации

📥 Загрузка калибровки

Подготовьте CSV файл с коэффициентамиПерейдите на страницу /readings
Нажмите "Выберите файл" в разделе калибровки
Выберите ваш CSV файл
Нажмите "Загрузить CSV"


🔄 Управление калибровкой

**Включить/выключить:** Переключатель в настройках
**Удалить таблицу:** Кнопка "Удалить CSV таблицу"
**Статус:** Отображается на странице показаний

---

🚀 Обновления прошивки

🔄 OTA обновления

Автоматическая проверка
Перейдите на страницу /updates
Нажмите "Проверить обновления"
Система автоматически найдет новые версии
При наличии обновления появится кнопка "Установить"


Ручная установка
Скачайте .bin файл прошивкиПерейдите на страницу /updates
Нажмите "Выберите файл"
Выберите скачанный .bin файл
Нажмите "Загрузить прошивку"


⚠️ Важные замечания

**Не отключайте питание** во время обновления
**Дождитесь завершения** процесса
**Система перезагрузится** автоматически
**Проверьте версию** после обновления

---

🔧 Сервисные функции

📊 Мониторинг системы

Системная информация
**Версия прошивки:** Текущая версия прошивки
**Время работы:** Время с последней перезагрузки
**Свободная память:** Доступная оперативная память
**Размер файловой системы:** Использование Flash памяти

Сетевые параметры
**IP адрес:** Текущий IP адрес устройства
**MAC адрес:** Уникальный идентификатор
**Сила сигнала WiFi:** Качество соединения
**Статус MQTT:** Подключение к MQTT брокеру

🛠️ Диагностика

Тест датчика
Проверка связи с JXCT датчиком:
Чтение всех параметров
Проверка целостности данных
Валидация диапазонов

Тест сети
Проверка сетевого подключения:
Доступность WiFi
Подключение к интернету
Работа DNS

Тест интеграций
Проверка внешних сервисов:
MQTT публикация
ThingSpeak отправка
NTP синхронизация

🔄 Управление устройством

Перезагрузка
Мягкая перезагрузка системы:
Сохранение всех настроек
Перезапуск всех сервисов
Очистка временных данных

Сброс настроек
Возврат к заводским настройкам:
**⚠️ Внимание:** Все настройки будут потеряны
WiFi настройки сброшены
MQTT/ThingSpeak отключены
Калибровка удалена

Очистка логов
Удаление старых логов:
Освобождение места в памяти
Улучшение производительности
Сброс счетчиков ошибок

---

❓ Часто задаваемые вопросы

🔧 Технические вопросы

**Q: Датчик показывает неверные значения**
A: Проверьте подключение, выполните калибровку, убедитесь в правильности типа почвы

**Q: Не подключается к WiFi**
A: Проверьте SSID и пароль, убедитесь в стабильности сигнала

**Q: MQTT не работает**
A: Проверьте настройки сервера, порт, логин и пароль

**Q: ThingSpeak не отправляет данные**
A: Проверьте API ключ и Channel ID, убедитесь в интернет-соединении

📊 Вопросы по данным

**Q: Что означают стрелки ↑↓ в показаниях?**
A: Показывают направление изменений после компенсации данных

**Q: Почему значения RAW и Компенс. отличаются?**
A: Компенсированные значения учитывают температуру, влажность и тип почвы

**Q: Как интерпретировать цветовую индикацию?**
A: Зеленый - норма, желтый - внимание, оранжевый - предупреждение, красный - критично

**Q: Откуда берутся рекомендации?**
A: На основе выбранной культуры, сезона и типа среды выращивания

🔬 Вопросы по калибровке

**Q: Нужна ли калибровка?**
A: Рекомендуется для повышения точности, но не обязательна

**Q: Как создать CSV файл калибровки?**
A: Используйте пример из /docs/examples/calibration_example.csv

**Q: Можно ли использовать калибровку от другого датчика?**
A: Не рекомендуется, каждый датчик индивидуален

**Q: Как проверить качество калибровки?**
A: Сравните показания с лабораторными измерениями

🌐 Вопросы по веб-интерфейсу

**Q: Не открывается веб-интерфейс**
A: Проверьте IP адрес, убедитесь в подключении к правильной сети

**Q: Интерфейс медленно загружается**
A: Проверьте качество WiFi соединения, перезагрузите устройство

**Q: Не сохраняются настройки**
A: Проверьте права доступа, убедитесь в достаточном месте в памяти

**Q: Как экспортировать данные?**
A: Используйте API /api/v1/sensor` или функцию экспорта CSV

---

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Техническая документация](TECHNICAL_DOCS.md)
[API документация](API.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта

---

**© 2025 JXCT Development Team**  
*Версия 3.4.9 | Июнь 2025* 
            ← Вернуться на главную
        
    





    
    
    Централизованное управление версией JXCT
    


    
        
            Централизованное управление версией JXCT
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🎯 Обзор](#-обзор)
[📁 Файл версии](#-файл-версии)
[🔧 Как изменить версию](#-как-изменить-версию)
[📋 Доступные макросы](#-доступные-макросы)
[🔍 Сравнение версий](#-сравнение-версий)
[🚀 Преимущества](#-преимущества)
[📝 Примеры использования](#-примеры-использования)
[🔄 Процесс релиза](#-процесс-релиза)
[⚠️ Важные замечания](#️-важные-замечания)
[🎯 Результат](#-результат)

---

🎯 Обзор

Начиная с версии 2.4.5, проект JXCT использует **централизованное управление версией**. Это означает, что версия определяется в одном месте и автоматически обновляется во всех частях проекта.

📁 Файл версии

**Файл:** include/version.h

Это единственное место, где нужно изменять версию проекта.

🔧 Как изменить версию

Простой способ
Отредактируйте файл include/version.h и измените только эти три строки:

``cpp
#define JXCT_VERSION_MAJOR 2    // Основная версия
#define JXCT_VERSION_MINOR 4    // Минорная версия  
#define JXCT_VERSION_PATCH 5    // Патч версия
`


**Пример:** Для версии 2.5.0:
`cpp
#define JXCT_VERSION_MAJOR 2
#define JXCT_VERSION_MINOR 5
#define JXCT_VERSION_PATCH 0
`

Автоматическое обновление

После изменения версии в version.h, она автоматически обновится в:


✅ **MQTT сообщениях** (sw_version в Home Assistant)
✅ **Веб-интерфейсе** (все страницы)
✅ **Баннере запуска** в Serial Monitor
✅ **API ответах** (/api/sensor, /health)
✅ **Логах системы**
✅ **OTA обновлениях**


📋 Доступные макросы

Основные макросы версии
`cpp
JXCT_VERSION_MAJOR          // 2
JXCT_VERSION_MINOR          // 4  
JXCT_VERSION_PATCH          // 5
JXCT_VERSION_STRING         // "2.4.5"
JXCT_VERSION_CODE           // 20405 (для сравнения)
`

Информация о сборке
`cpp
JXCT_BUILD_DATE             // "Dec 25 2024"
JXCT_BUILD_TIME             // "15:30:45"
JXCT_FULL_VERSION_STRING    // "2.4.5 (built Dec 25 2024 15:30:45)"
`

Константы устройства
`cpp
DEVICE_MANUFACTURER[]       // "Eyera"
DEVICE_MODEL[]             // "JXCT-7in1"
DEVICE_SW_VERSION[]        // "2.4.5" (автоматически)
FIRMWARE_VERSION           // "2.4.5" (для совместимости)
`

🔍 Сравнение версий

Для проверки версии в коде:

`cpp
// Проверка минимальной версии
#if JXCT_VERSION_AT_LEAST(2, 4, 5)
    // Код для версии 2.4.5 и выше
#endif

// Проверка точной версии
#if JXCT_VERSION_CODE == 20405  // 2.4.5
    // Код только для версии 2.4.5
#endif
`


🚀 Преимущества

✅ До (проблемы):
Версия была разбросана по 4+ файлам
При обновлении легко забыть какой-то файл
Версии в MQTT и веб-интерфейсе могли не совпадать
Ручное обновление каждого места

✅ После (решение):
**Одно место** для изменения версии
**Автоматическое обновление** везде
**Гарантированная согласованность**
**Простота сопровождения**

📝 Примеры использования

В коде C++
`cpp
#include "version.h"

void printVersion() {
    Serial.println("Версия: " JXCT_VERSION_STRING);
    Serial.println("Полная версия: " JXCT_FULL_VERSION_STRING);
}
`


В MQTT сообщениях
`cpp
doc["device"]["sw_version"] = DEVICE_SW_VERSION;  // Автоматически "2.4.5"
`

В веб-интерфейсе
`cpp
html += "Версия: " + String(FIRMWARE_VERSION);  // Автоматически "2.4.5"
`

🔄 Процесс релиза

**Измените версию** в include/version.h
**Скомпилируйте** проект (pio run)
**Проверьте** что версия обновилась везде
**Создайте коммит** с новой версией
**Создайте тег** в Git: git tag v2.4.5


⚠️ Важные замечания

**НЕ изменяйте** версию в других файлах - она перезапишется
**Всегда компилируйте** после изменения версии
**Используйте семантическое версионирование**: MAJOR.MINOR.PATCH
**Обновляйте CHANGELOG.md** при изменении версии

🎯 Результат

Теперь для изменения версии во всем проекте достаточно изменить **3 строки** в **1 файле**!

`cpp
// Было: изменения в 4+ файлах
// Стало: изменения в 1 файле
#define JXCT_VERSION_PATCH 6  // Изменили только эту строку
// Версия автоматически обновилась везде! 🎉
``

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Схема подключения](WIRING_DIAGRAM.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную
        
    





    
    
    Схема подключения
    


    
        
            Схема подключения
            
                Версия: 3.4.9 | 
                Дата: Июнь 2025 | 
                Автор: JXCT Development Team
            
        
        
        
            🏠 Главная 👤 Руководство пользователя 🔧 Техническая документация 📡 API 📚 API документация
        
        
        
            
**Версия:** 3.4.9  
**Дата:** Июнь 2025  
**Автор:** JXCT Development Team

---

📖 Содержание

[🔌 RS-485 соединение](#-rs-485-соединение)
[⚡ Питание датчика](#-питание-датчика)
[⚠️ Важные замечания](#️-важные-замечания)
[🔧 Рекомендации по монтажу](#-рекомендации-по-монтажу)

---

🔌 RS-485 соединение

ESP32 → RS-485 Transceiver (SP3485E)

SP3485E (3.3V логика)



ESP32 GPIO
SP3485E Pin
Тип сигнала
Описание




GPIO16
RO
Цифровой вход
UART2 RX - прием данных от SP3485E


GPIO17
DI
Цифровой выход
UART2 TX - передача данных в SP3485E


GPIO5
DE/RE
Цифровой выход
Управление направлением передачи


3.3V
VCC
Питание
Питание модуля SP3485E


GND
GND
Земля
Общий провод



Преимущества SP3485E:
✅ **Питание от 3.3V** - не требует преобразования уровней
✅ **Высокая скорость** - до 10 Mbps
✅ **Низкое энергопотребление** - всего 300μA в режиме ожидания
✅ **Защита от ESD** - до ±15kV HBM
✅ **Встроенная защита** от перенапряжения на линии RS-485

Подключение датчика JXCT




SP3485E Pin
JXCT Pin
Тип сигнала
Описание




A
A+
RS-485 A
Неинвертирующая линия RS-485


B
B-
RS-485 B
Инвертирующая линия RS-485



⚡ Питание датчика

Требования к питанию
**SP3485E:** питается от 3.3V ESP32 (оптимально для ESP32)
**Датчик:** требует отдельное питание 12-24V
**Общий провод (GND):** соединить все устройства
**Терминирование:** резистор 120Ω между A и B на концах линии

Схема подключения питания




Блок питания
JXCT Pin
Описание




V+
V+
12-24V питание датчика


GND
GND
Общий провод



⚠️ Важные замечания

Критические моменты
**Полярность:** строго соблюдать подключение A+ и B-
**Заземление:** обеспечить надежное заземление всех устройств
**Экранирование:** использовать экранированную витую пару
**Длина линии:** при длинных линиях использовать терминирующие резисторы

🔧 Рекомендации по монтажу

Используйте экранированную витую пару для RS-485
Соблюдайте полярность подключения A+ и B-
Обеспечьте надежное заземление
При длинных линиях используйте терминирующие резисторы

📞 Поддержка

💬 Связь с разработчиками
**Telegram:** [@Gfermoto](https://t.me/Gfermoto)
**GitHub Issues:** [Сообщить о проблеме](https://github.com/Gfermoto/soil-sensor-7in1/issues)
**Документация:** [GitHub Pages](https://gfermoto.github.io/soil-sensor-7in1/)

📚 Дополнительные ресурсы
[Руководство пользователя](USER_GUIDE.md)
[Техническая документация](TECHNICAL_DOCS.md)
[Агрономические рекомендации](AGRO_RECOMMENDATIONS.md)
[Руководство по компенсации](COMPENSATION_GUIDE.md)
[API документация](API.md)
[Управление конфигурацией](CONFIG_MANAGEMENT.md)
[Протокол Modbus](MODBUS_PROTOCOL.md)
[Управление версиями](VERSION_MANAGEMENT.md)

🔗 Полезные ссылки

[🌱 GitHub репозиторий](https://github.com/Gfermoto/soil-sensor-7in1) - Исходный код проекта
[📋 План рефакторинга](../dev/QA_REFACTORING_PLAN_2025H2.md) - Планы развития на 2025
[📊 Отчет о техническом долге](../dev/TECH_DEBT_REPORT_2025-06.md) - Анализ технических проблем
[🏗️ Архитектура системы](../dev/ARCH_OVERALL.md) - Общая архитектура проекта 
            ← Вернуться на главную

Параметр	Диапазон	Точность	Единицы
Температура	0-50°C	±0.5°C	°C
Влажность	0-100%	±3%	%
EC	0-5000	±5%	µS/cm
pH	3-9	±0.3	pH
Азот	0-2000	±10%	мг/кг
Фосфор	0-1000	±10%	мг/кг
Калий	0-2000	±10%	мг/кг

Адрес	Описание	Единицы	Диапазон
0x0001	Температура	0.1°C	-400-800
0x0002	Влажность	0.1%	0-1000
0x0003	EC	1 µS/cm	0-65535
0x0004	pH	0.1 pH	0-140
0x0005	Азот	1 мг/кг	0-65535
0x0006	Фосфор	1 мг/кг	0-65535
0x0007	Калий	1 мг/кг	0-65535

Датчик	ESP32	Описание
VCC	3.3V	Питание
GND	GND	Земля
TX	GPIO2	Передача данных
RX	GPIO4	Прием данных

Культура	Температура	Влажность	EC	pH	N	P	K
Томаты	22°C	60%	1500	6.5	40	10	30
Огурцы	24°C	70%	1800	6.2	35	12	28
Перец	23°C	65%	1600	6.3	38	11	29
Салат	20°C	75%	1000	6.0	30	8	25
Голубика	18°C	65%	1200	5.0	30	10	20
Газон	20°C	50%	800	6.3	25	8	20

ESP32 GPIO	SP3485E Pin	Тип сигнала	Описание
GPIO16	RO	Цифровой вход	UART2 RX - прием данных от SP3485E
GPIO17	DI	Цифровой выход	UART2 TX - передача данных в SP3485E
GPIO5	DE/RE	Цифровой выход	Управление направлением передачи
3.3V	VCC	Питание	Питание модуля SP3485E
GND	GND	Земля	Общий провод

SP3485E Pin	JXCT Pin	Тип сигнала	Описание
A	A+	RS-485 A	Неинвертирующая линия RS-485
B	B-	RS-485 B	Инвертирующая линия RS-485

Блок питания	JXCT Pin	Описание
V+	V+	12-24V питание датчика
GND	GND	Общий провод