# AS7341 STEM-Лаборатория — Полное руководство

**Платформа:** ESP32 DEVKIT V1 + Adafruit AS7341  
**Прошивка:** `src/main.cpp` (Ядро), `src/As7341Lab.cpp` (Драйвер)  
**Визуализация:** `monitor.py` (Python 3 + Matplotlib)

---

## Содержание

1. [Что такое AS7341](#1-что-такое-as7341)
2. [Подключение и запуск](#2-подключение-и-запуск)
3. [Параметры датчика — как менять и трактовать](#3-параметры-датчика)
4. [Режим S — Спектр (Физика)](#4-режим-s--спектр-физика)
5. [Режим A — Поглощение (Химия)](#5-режим-a--поглощение-химия)
6. [Режим P — PAR (Биология / Гидропоника)](#6-режим-p--par-биология--гидропоника)
7. [Режим C — Цветовая температура (Физика / Умный дом)](#7-режим-c--цветовая-температура)
8. [Режим I — ИК-детектор (Физика)](#8-режим-i--ик-детектор-физика)
9. [Лабораторные сценарии по предметам](#9-лабораторные-сценарии)
10. [Гидропоника — практическое применение](#10-гидропоника)
11. [Глоссарий](#11-глоссарий)

---

## 1. Что такое AS7341

AS7341 — **11-канальный спектрофотометр на одном чипе** размером 3×2 мм. Это не RGB-датчик. Он независимо измеряет интенсивность в каждом спектральном диапазоне.

| Канал | Длина волны | Цвет       | Физический смысл                          |
|-------|-------------|------------|-------------------------------------------|
| F1    | 415 нм      | Фиолетовый | Граница видимого / UVA                    |
| F2    | 445 нм      | Синий      | Пик поглощения хлорофилла A               |
| F3    | 480 нм      | Голубой    | Синяя компонента неба, мониторы           |
| F4    | 515 нм      | Зелено-голубой | Переход к зелёному                   |
| F5    | 555 нм      | Зелёный    | Максимум чувствительности глаза           |
| F6    | 590 нм      | Жёлтый     | Натриевые лампы, закат                    |
| F7    | 630 нм      | Оранжево-красный | Фотосинтетически активный диапазон |
| F8    | 680 нм      | Красный    | Пик поглощения хлорофилла B               |
| NIR   | ~910 нм     | Ближний ИК | Невидимый диапазон, пульты ДУ, нагрев     |
| Clear | широкополосный | Белый | Суммарная освещённость (аналог люксметра) |

---

## 2. Подключение и запуск

### Схема подключения (I2C)

```
AS7341          ESP32 DEVKIT V1
  VCC  ──────►  3.3V  (или 5V если модуль со стабилизатором)
  GND  ──────►  GND
  SDA  ──────►  GPIO 21
  SCL  ──────►  GPIO 22
```

> **Совет:** Положи поверх датчика кусочек белого матового пластика (диффузор) — иначе датчик видит только узкую точку источника и даёт систематическую погрешность при рассеянном свете.

### Сборка и загрузка прошивки

```bash
# В PlatformIO (VS Code) — нажми Upload
# или в терминале:
pio run --target upload
```

### Установка зависимостей Python (один раз)

```bash
python3 -m pip install -r requirements.txt
# или вручную: python3 -m pip install pyserial matplotlib
```

### Запуск визуализации (закрой Serial Monitor перед этим!)

```bash
python3 monitor.py /dev/ttyUSB0
# Порт определяется автоматически если не указать
```

Управление кнопками прямо в окне Python: режимы `S/A/P/C/I`, `Ref/B` (сохранить reference для поглощения) и **`Gain -`/`Gain +`** — это единственный способ менять усиление, пока открыт `monitor.py` (Serial Monitor PlatformIO в это время **должен быть закрыт**, оба не могут держать порт одновременно). Если физическая связь с датчиком по I2C оборвётся, строка статуса в окне мигнёт красным `!! СВЯЗЬ С AS7341 ПОТЕРЯНА !!` — это `As7341Lab::isAlive()` из прошивки, а не сбой самого скрипта.

---

## 3. Параметры датчика

### Gain (Усиление)

Gain управляет чувствительностью сенсора. Все значения на выходе умножаются на коэффициент усиления.

| Gain   | Когда применять                                         |
|--------|---------------------------------------------------------|
| 0.5x–2x | Прямой солнечный свет, яркие прожекторы               |
| 4x–32x  | Стандартное помещение, офис, класс                    |
| **64x** | **По умолчанию.** Нормальное искусственное освещение   |
| 128x–256x | Слабое освещение, сумерки, тёмные растворы          |
| 512x    | Почти темнота, люминесценция, слабые источники         |

Всего доступно 11 ступеней (0.5x, 1x, 2x, 4x, 8x, 16x, 32x, 64x, 128x, 256x, 512x) — полный список из даташита AS7341, регистр AGAIN.

**Признаки неверного Gain:**
- Канал показывает `65535` — **перегруз**, нажми `-` (уменьшить Gain)
- Все значения < 100 — **недостаточно**, нажми `+` (увеличить Gain)

Команды в режиме прошивки: `+` / `-` (через Serial Monitor или кнопкой `+`/`-` если добавить в Python).

### ATIME и ASTEP — время интегрирования

Общее время одного замера вычисляется по формуле:

```
T_int = (ATIME + 1) × (ASTEP + 1) × 2.78 мкс
```

При значениях по умолчанию (`ATIME=100`, `ASTEP=999`):

```
T_int = 101 × 1000 × 2.78 мкс ≈ 280 мс
```

| Параметр | Увеличить → | Уменьшить → |
|----------|-------------|-------------|
| ATIME    | точнее, медленнее | быстрее, шумнее |
| ASTEP    | точнее, медленнее | быстрее, шумнее |

Для экспериментов с быстрыми событиями (мигающий пульт ДУ) уменьши ATIME до 10–20. Для точной спектрофотометрии растворов увеличь до 200+.

---

## 4. Режим S — Спектр (Физика)

**Команда:** `S`  
**График:** столбчатая диаграмма, каждый столбик на своей длине волны, закрашен физическим цветом.

### Что показывает

Спектральный «отпечаток» источника света — распределение энергии по длинам волн.

### Как читать

| Форма спектра | Источник |
|---|---|
| Плавная колоколообразная кривая, максимум ~600–700 нм | Лампа накаливания / солнце |
| Острый пик на 445–480 нм + малый «хвост» | Дешёвый белый LED (холодный) |
| Два пика: 445 нм и 590–630 нм, провал в середине | Качественный тёплый LED |
| Один высокий пик на 555 нм | Монохроматический зелёный лазер |
| Равномерно высокие все каналы | Прямой солнечный свет (ясный день) |

### Эксперименты

**«Анатомия белого света»**  
Направь датчик на разные источники по очереди: свечу, лампу накаливания, холодный LED, тёплый LED, монитор ноутбука. Ученики видят, что «белый» у каждого разный.

**«Сравнение ламп»**  
Купи в магазине 3 лампочки с надписями "2700K", "4000K", "6500K". Сделай снимок спектра каждой. Видно как смещается баланс 445/680 нм.

---

## 5. Режим A — Поглощение (Химия)

**Команда:** `A`, затем `B` (сохранить reference)  
**График:** столбчатая диаграмма оптической плотности по 8 каналам.

### Физический закон

**Закон Бугера–Ламберта–Бера:**

$$A_\lambda = \log_{10}\frac{I_0}{I} = \varepsilon \cdot c \cdot l$$

- $A_\lambda$ — оптическая плотность (безразмерная)
- $I_0$ — интенсивность до вещества (reference, сохраняется кнопкой `B`)
- $I$ — интенсивность после прохождения через вещество
- $\varepsilon$ — молярный коэффициент поглощения (константа вещества)
- $c$ — концентрация раствора
- $l$ — длина оптического пути (толщина кюветы)

**Практический вывод:** чем больше $A$, тем более концентрированный раствор или тем гуще окраска.

### Протокол эксперимента

1. Поставь **пустой стакан с чистой водой** перед датчиком
2. Включи режим A, нажми `B` → reference сохранён
3. Добавляй в воду **краситель по каплям** и наблюдай рост $A$ на нужных длинах волн
4. Записывай количество капель и значение $A$ — получишь **калибровочную кривую**

### Вещества и их спектры поглощения

| Вещество              | Пик поглощения | Канал AS7341 |
|-----------------------|----------------|--------------|
| Марганцовка (KMnO₄)  | 525–550 нм     | F5 (555 нм)  |
| Хлорофилл (листья)   | 445 + 680 нм   | F2 + F8      |
| Йод (I₂ в воде)      | 450–490 нм     | F2–F3        |
| Синие чернила        | 590–630 нм     | F6–F7        |
| Красный краситель     | 480–515 нм     | F3–F4        |
| Медный купорос CuSO₄ | 600–700 нм     | F7–F8        |

> **Важно:** Освещение во время опыта должно быть стабильным. Используй светодиодный фонарик сбоку от кюветы, направленный строго на датчик. Флуоресцентные лампы мерцают (50 Гц) и создают шум.

---

## 6. Режим P — PAR (Биология / Гидропоника)

**Команда:** `P`  
**График:** линия PAR-индекса с историей, цветные зоны, крупное текущее значение по центру.

### Что такое PAR

**PAR (Photosynthetically Active Radiation)** — фотосинтетически активная радиация. Диапазон 400–700 нм, который растения используют для фотосинтеза.

Хлорофилл A поглощает максимально на **445 нм** (синий) и **680 нм** (красный). Зелёный (~555 нм) в основном отражается — отсюда зелёный цвет листьев.

### Формула (AS7341)

```
PAR = (F2×1.0 + F1×0.3 + F3×0.6) × Blue_weight
    + (F8×1.0 + F7×0.8) × Red_weight
    + (F4×0.2 + F5×0.1 + F6×0.05) × Green_weight
    / 3000   (нормировочный коэффициент)
```

### Интерпретация значений

| PAR-индекс | Зона (цвет) | Что это значит | Для каких растений |
|---|---|---|---|
| < 0.10 | Красная | Глубокая тень | Мхи, папоротники |
| 0.10–0.30 | Жёлтая | Слабое освещение | Монстера, сансевиерия |
| 0.30–0.70 | Светло-зелёная | Нормальный рассеянный свет | Большинство комнатных |
| > 0.70 | Ярко-зелёная | Полное освещение | Томаты, базилик, огурцы, гидропоника |

### Почему показывает низкий PAR в помещении

Обычная лампа накаливания 60W даёт слабый синий компонент (445 нм) — PAR будет занижен даже при высоком Clear. Специальная **фитолампа** имеет усиленные пики именно в синем и красном, и PAR резко вырастет.

---

## 7. Режим C — Цветовая температура

**Команда:** `C`  
**График:** линия CCT в Кельвинах с историей, горизонтальные пунктиры-ориентиры.

### Физика цветовой температуры

Цветовая температура — это температура «абсолютно чёрного тела», излучение которого на вид совпадает с данным источником света. Измеряется в **Кельвинах (K)**.

| CCT | Источник | Ощущение |
|-----|----------|----------|
| 1800–2200 K | Свеча, огонь | Очень тёплый, оранжевый |
| 2700 K | Лампа накаливания | Тёплый, жёлтый |
| 3000–3500 K | Галоген, тёплый LED | Уютный |
| 4000–4500 K | Нейтральный белый LED | Офис, класс |
| 5000–5500 K | Прямой солнечный свет | Дневной |
| 6000–6500 K | Пасмурное небо | Холодный белый |
| > 7000 K | Синее ясное небо, HMI | Холодный голубой |

### Метод расчёта (McCamy)

Сначала из 8 спектральных каналов вычисляются координаты CIE XYZ через веса функций согласования цвета, затем хроматические координаты $x, y$, затем:

$$n = \frac{x - 0.3320}{0.1858 - y}$$

$$CCT = -449n^3 + 3525n^2 - 6823.3n + 5520.33$$

### Применение для умного отеля / класса

- CCT > 5000 K после 20:00 → автоматически переключить лампы на 2700 K (подавление мелатонина)
- CCT < 4000 K утром → включить холодный белый (бодрящий эффект)
- Мониторинг деградации LED: со временем CCT смещается в синюю сторону

### «Светофор здоровья» в monitor.py

Панель справа в окне визуализации — не отдельный график, а живая реализация правила выше: [`circadian_health()`, monitor.py:367](monitor.py#L367) сочетает CCT, отношение синего к общей яркости `(F2+F3)/Clear` и текущее время суток (`datetime.now().hour`) в один из четырёх статусов:

| Время суток | Условие (код) | Статус | Смысл |
|---|---|---|---|
| Ночь 22:00–6:00 | CCT > 3200 K **или** синего > 25% | 🔴 ОПАСНО | синий свет ночью подавляет мелатонин |
| Ночь 22:00–6:00 | иначе | 🟢 ХОРОШО | тёплый свет, мелатонину не мешает |
| Вечер 20:00–22:00 | CCT > 4500 K **или** синего > 30% | 🔴 ОПАСНО | пора выключать холодный свет |
| Вечер 20:00–22:00 | CCT > 3200 K | 🟡 ВНИМАНИЕ | лучше переключить на тёплый (~2700 K) |
| День 6:00–20:00 | CCT > 3000 K | 🟢 ХОРОШО/ОТЛИЧНО | нейтральный/холодный свет уместен днём |
| Любое время | `Clear` < 150 | ⚪ ТЕМНО | света мало, оценка ненадёжна |

Панель отвечает на вопрос «правильный ли сейчас свет для организма» — прямое практическое следствие теории цветовой температуры из раздела 7 THEORY.md, а не просто число в Кельвинах.

---

## 8. Режим I — ИК-детектор (Физика)

**Команда:** `I`  
**График:** две линии (NIR и VIS) + пунктирная линия коэффициента NIR/VIS на второй оси.

### Что измеряет

| Канал | Что видит |
|---|---|
| NIR (~910 нм) | Ближний инфракрасный: пульты ДУ, нагретые тела, солнечный ИК |
| VIS (сумма F1–F8) | Весь видимый диапазон 415–680 нм |
| NIR/VIS | Отношение: «насколько ИК больше видимого» |

### Интерпретация коэффициента NIR/VIS

| Значение | Интерпретация |
|---|---|
| > 2.0 | Пульт ДУ направлен прямо (мощный ИК-импульс) |
| 0.8–2.0 | Прямой солнечный свет (содержит ~50% ИК) |
| 0.3–0.8 | Тёплый LED или галоген |
| < 0.3 | Холодный LED, монитор (почти нет ИК) |

### Эксперименты

**«Невидимый мир»** — направь пульт ДУ телевизора на датчик. NIR всплёскивает при каждом нажатии кнопки, VIS стоит неподвижно. Идеальная демонстрация существования ИК-излучения.

**«Нагретые тела»** — поднеси к датчику горячую кружку. NIR медленно растёт по мере нагрева поверхности.

**«Солнце vs LED»** — выйди на улицу, сравни NIR/VIS уличного солнца и комнатной лампы. Разница принципиальная.

---

## 9. Лабораторные сценарии

### Физика

| Тема урока | Режим | Опыт | Ожидаемый результат |
|---|---|---|---|
| Дисперсия света | S | Призма перед датчиком | Пики смещаются в зависимости от угла |
| Электромагнитный спектр | I | Пульт ДУ | NIR растёт, VIS = const |
| Излучение чёрного тела | C + S | 3 лампы с разной CCT | Сдвиг спектра с температурой |
| Поглощение света | A | Стакан с водой + краситель | Рост A в определённых каналах |
| Закон Кирхгофа | S | Натриевая лампа | Острый пик на 590 нм |

### Химия

| Тема урока | Режим | Вещество | Что измеряем |
|---|---|---|---|
| Концентрация раствора | A | Марганцовка | A пропорционально концентрации |
| Качественный анализ | A | Неизвестный раствор | Идентификация по пику поглощения |
| Фотометрия | A | Медный купорос | Калибровочная кривая A(c) |
| Окислительно-восстановительные | A | KMnO₄ → MnO₂ | Пик 555 нм исчезает при реакции |

### Биология

| Тема урока | Режим | Опыт | Что наблюдаем |
|---|---|---|---|
| Фотосинтез | P | Фитолампа vs обычная лампа | Разница PAR в разы |
| Пигменты хлорофилла | A | Вытяжка из листьев | Пики F2 (445) и F8 (680) |
| Влияние спектра на рост | P | Разные лампы над растением | PAR-индекс как критерий выбора лампы |
| Хроматография | A | Разделённые пигменты | Каждая фракция — свой пик |

### Гидропоника / Агро-STEM

| Задача | Режим | Критерий |
|---|---|---|
| Подобрать лампу для рассады | P | PAR > 0.70 |
| Контролировать световой день | C + P | CCT + PAR каждые N часов |
| Детектировать деградацию лампы | S | Смещение пика 445/680 со временем |
| Сравнить натуральный и искусственный свет | S + P | Снять спектр у окна и под лампой |

---

## 10. Гидропоника

### Что важно для растений по спектру

```
Вегетация (рост листьев):   Синий 415–480 нм  →  высокий F1, F2, F3
Цветение и плодоношение:    Красный 630–680 нм →  высокий F7, F8
Ингибирование вытягивания:  Синий > Красного   →  F2/F8 > 1.0
Максимальный фотосинтез:    PAR > 0.70
```

### Практический регламент замеров

1. **Ежедневно в одно время** (например, 12:00) фиксировать PAR и CCT над каждой грядкой
2. Если PAR < 0.3 → добавить фитолампу или поднять (мощность)
3. Если спектр сместился (445 нм растёт относительно 680 нм) → лампа выгорает, менять
4. Для рассады томатов/перца: добавь синего (445 нм) — стебли будут короче и крепче
5. За 2 недели до уборки: увеличь красный (680 нм) — ускорит созревание

### Формула отношения Blue:Red (B/R)

$$\frac{B}{R} = \frac{F_2 (445\,\text{нм})}{F_8 (680\,\text{нм})}$$

| B/R | Эффект на растение |
|---|---|
| > 2.0 | Компактный рост, тёмно-зелёные листья |
| 1.0–2.0 | Сбалансированный рост |
| < 1.0 | Вытягивание, светло-зелёный цвет (нехватка синего) |

---

## 11. Глоссарий

**ATIME** — параметр времени интегрирования (0–255). Вместе с ASTEP определяет длительность одного замера. Увеличить = точнее и медленнее.

**ASTEP** — шаг времени интегрирования (0–65534). Умножается на ATIME + 1. Смотри формулу в разделе 3.

**Beer-Lambert / Бугер–Ламберт–Бер** — закон, связывающий поглощение света с концентрацией вещества: $A = \log_{10}(I_0/I)$. Основа количественного анализа в химии.

**B/R ratio** — отношение синего (445 нм) к красному (680 нм) в спектре лампы. Критерий для агрономии.

**CCT (Correlated Color Temperature)** — коррелированная цветовая температура. Кельвины. Тёплый = низкий, холодный = высокий.

**Clear channel** — широкополосный канал без спектрального фильтра. Аналог люксметра. Не заменяет специализированный люксметр, но пригоден для сравнительных измерений.

**Counts** — единица измерения AS7341. Целое число от 0 до 65535. Зависит от Gain и ATIME. Для сравнения источников нужно фиксировать одинаковые настройки.

**Gain (усиление)** — коэффициент усиления аналогового сигнала перед АЦП. Диапазон 0.5x–512x. Не влияет на физическую реальность — только на чувствительность схемы.

**NIR (Near Infrared)** — ближний инфракрасный диапазон. Канал AS7341 центрирован около 910 нм. Невидим для глаза. Присутствует в солнечном свете, пультах ДУ, нагретых телах.

**PAR (Photosynthetically Active Radiation)** — фотосинтетически активная радиация. Диапазон 400–700 нм, взвешенный по поглощению хлорофилла. Единица PPFD = мкмоль фотонов/(м²·с). Индекс в прошивке — безразмерное нормированное число.

**PAR-индекс** — собственная нормированная величина данной прошивки (не PPFD). Используется для сравнения источников между собой. Значение 1.0 соответствует примерно полному дневному освещению при Gain=64x.

**Спектр поглощения** — зависимость оптической плотности вещества от длины волны. Уникален для каждого вещества — «отпечаток пальца» молекулы.

**Спектр излучения** — распределение мощности источника по длинам волн. У лампы накаливания — непрерывный (тепловой), у LED — с пиками.

**CIE XYZ** — стандартное трёхстимульное цветовое пространство. Используется для расчёта CCT из спектральных данных.

**Хроматические координаты x, y** — нормированные проекции XYZ на плоскость. Определяют «цветность» без учёта яркости. На их основе работает формула McCamy для CCT.

**I2C** — двупроводной последовательный протокол связи. SDA = данные, SCL = тактирование. Адрес AS7341 по умолчанию 0x39.

**Диффузор** — рассеивающее стекло / матовый пластик перед датчиком. Усредняет освещение по площади датчика. Обязателен для точных абсолютных измерений.

---

## Быстрая шпаргалка — что делать если...

| Симптом | Действие |
|---|---|
| Все каналы = 65535 | Нажми `-` несколько раз (уменьшить Gain) |
| Все каналы < 50 | Нажми `+` несколько раз (увеличить Gain) |
| PAR всегда 0 | Закрой PlatformIO Serial Monitor, запусти только monitor.py |
| Жёлтый график остаётся на всех режимах | Перезапусти monitor.py |
| CCT = 0 или отрицательный | Слишком темно, увеличь Gain или добавь света |
| Режим A не показывает поглощение | Нажми `B` сначала при пустой кювете |
| monitor.py не видит порт | Проверь `ls /dev/ttyUSB*` или `/dev/ttyACM*` |

---

## 12. Программная архитектура

Код проекта переведен на модульную объектно-ориентированную структуру для удобства интеграции в Sensor Hub.

- **`include/As7341Lab.h`**: Интерфейс класса лаборатории. Структура `Data` (10 каналов датчика), режимы, doxygen-описание каждого публичного метода.
- **`src/As7341Lab.cpp`**: Реализация всей математической логики (PAR, CCT, Beer-Lambert) и методов визуализации. Все авторские расчеты и комментарии вынесены сюда.
- **`src/main.cpp`**: Главный файл управления. Обрабатывает Serial-команды и дирижирует работой датчика через объект класса `As7341Lab`.

Такой подход позволяет использовать спектрометр в больших проектах одной строчкой кода: `As7341Lab lab;`.

### Чтение данных и вотчдог связи

Драйвер хранит последний снимок внутри себя — снаружи данные не передаются напрямую:

```cpp
if (lab.read()) {                       // As7341Lab.cpp:29 — обновляет внутренний буфер
    const As7341Lab::Data &d = lab.getData(); // As7341Lab.h — const-ссылка на снимок
    ...
}
if (!lab.isAlive()) {                    // As7341Lab.h — true, если было успешное read() за последние 2000 мс
    Serial.println("Связь потеряна");
}
```

`isAlive()` не про "датчик исправен", а про "физический канал связи жив прямо сейчас" — обрыв провода I2C сразу виден в `main.cpp`, а не тихо застывает на последних показаниях.

## 13. Работа через CLI (PlatformIO)

Для управления проектом через терминал используйте следующие команды:

### Сборка и прошивка
```bash
cd Components/AS734x
pio run -t upload
```

### Мониторинг данных (Текст)
```bash
pio device monitor
```

### Графическая визуализация (Python)
Убедитесь, что закрыт `pio device monitor`, затем:
```bash
python3 monitor.py
```

## 14. Дополнительная документация
- [THEORY.md](THEORY.md) — Глубокая физика и математика спектра.
- [WIRING.md](WIRING.md) — Схемы и советы по подключению.
- [PREZ.md](PREZ.md) — Краткая презентация возможностей проекта.
- [Lesson.md](Lesson.md) — Методический план серии уроков (физика, химия, биология, технологии) для учителя.