# Контроллер насосов v8.2 — руководство пользователя

Документ для монтажника и обслуживающего персонала.
Техническое описание кода — в [README.md](README.md).

---

## 1. Что делает прибор

Контроллер следит за тремя насосами:

* **Насос 1** и **Насос 2** — основные;
* **Резерв** — аварийный (экстренный) насос.

Прибор:

1. показывает состояние на экране;
2. включает выход «Авария», если **оба** основных насоса остановлены;
3. включает выход «Резерв», когда запускается резервный насос;
4. отправляет уведомления на сервер (webhook) через интернет;
5. показывает панель мониторинга в браузере в локальной сети.

---

## 2. Подключение

### 2.1 Питание

5 В через microUSB (блок питания не менее 500 мА).

### 2.2 Датчики насосов

К каждому входу подключается **сухой контакт** — свободный контакт пускателя
насоса или датчика потока.

| Клемма платы | Что подключить |
|---|---|
| `D5` и `GND` | Контакт насоса 1 |
| `D6` и `GND` | Контакт насоса 2 |
| `D7` и `GND` | Контакт резервного насоса |

**Контакт замкнут = насос работает.** Полярность не важна, внешние резисторы
и питание на контакты подавать не нужно.

### 2.3 Выходы на реле

Прибор рассчитан на **релейные модули с активным LOW** — те, у которых реле
включается замыканием входа на GND. Это самый распространённый тип модулей для
Arduino.

| Клемма платы | Куда | Реле включается когда |
|---|---|---|
| `D3` | вход `IN` модуля «Авария» | оба основных насоса стоят |
| `D4` | вход `IN` модуля «Резерв» | работает резервный насос |

Питание модулей — от `5V` и `GND` платы (или от отдельного источника с общим
GND). **Сирену, лампу или пускатель напрямую к `D3`/`D4` подключать нельзя** —
только через релейный модуль или транзисторный ключ.

> **Важно: тип модуля должен быть именно active-LOW.** Если поставить модуль с
> активным HIGH, реле будет включено в норме и отпускать при аварии — логика
> перевернётся. Пины `D3` и `D4` выбраны именно под active-LOW: они удерживают
> HIGH во время загрузки платы, поэтому реле молчат при включении питания.

Оговорки, которые лучше знать заранее:

* Реле «Авария» **щёлкает при каждой заливке прошивки** — схема автосброса USB
  дёргает `D3`. Это нормально.
* Встроенный светодиод платы повторяет состояние реле «Резерв» — удобно для
  проверки монтажа.
* Схема **не отказобезопасная**: если контроллер обесточен, сигнала аварии нет.
  Если это критично — снимайте нагрузку с **нормально замкнутого (NC)** контакта
  реле, тогда пропажа питания читается системой как авария.

### 2.4 Свободные клеммы

`D8`, `D0` и `A0` прошивкой не используются. Учтите, что `A0` — только
аналоговый вход и цифровым выходом стать не может.

### 2.5 Экран

OLED 128×64 (I2C): `SDA → D1`, `SCL → D2`, `VCC → 3V3`, `GND → GND`.

---

## 3. Первое включение

1. Подайте питание. На экране появится `PUMP CTRL v8 / Starting...`.
2. Прибор не найдёт сохранённой сети и поднимет свою точку доступа:

   ```
   Имя сети: Pump_Control_Set
   ```

3. Подключитесь к ней с телефона или ноутбука (пароль не требуется).
4. Откройте в браузере `http://192.168.4.1` — откроется страница настройки.
5. Выберите вашу Wi-Fi-сеть, введите пароль, нажмите **Save**.
6. Прибор перезагрузится и покажет на экране полученный IP-адрес.
   **Запишите этот адрес** — по нему открывается панель мониторинга.

Если за 2 минуты сеть не настроена, прибор переходит в автономный режим:
экран, выходы аварии и логика работают, webhook и веб-панель — нет.

---

## 4. Экран

```
  PUMP CONTROLLER v8
────────────────────────
PUMP 1 : RUNNING
PUMP 2 : STOPPED
BACKUP : STANDBY
────────────────────────
192.168.1.42
STATUS: OK
```

| Надпись | Значение |
|---|---|
| `PUMP 1/2 : RUNNING` | Насос работает |
| `PUMP 1/2 : STOPPED` | Насос остановлен |
| `BACKUP : ACTIVE` | Резервный насос запущен |
| `BACKUP : STANDBY` | Резерв в ожидании |
| `WiFi: NO CONNECTION` | Нет связи с сетью |
| `INIT...` | Идёт запуск (первые ~4 секунды) |
| `STATUS: OK` | Норма |
| `WARN: BACKUP RUNNING` | Работает резерв — требуется внимание |
| `!! ALARM: NO PUMPS !!` (мигает) | **Авария: подача воды прекращена** |

---

## 5. Панель в браузере

Откройте `http://<IP-адрес прибора>` в любом браузере в той же сети.

На странице:

* три карточки насосов с индикаторами;
* панель состояния системы (`SYS_OK` или `CRITICAL`);
* **состояние обоих реле** — «Включено» / «Выключено»;
* кнопка **Сбросить Wi-Fi**;
* блок **Настройки** — адрес уведомлений, имя устройства и две выдержки.

Страница обновляется автоматически при изменении состояния насосов или реле.

### 5.1 Состояние реле

Два индикатора показывают, что прибор реально подал на выход:

| Индикатор | Значение |
|---|---|
| Реле «Авария» — Включено | Выход `D3` активен, сигнал аварии выдан |
| Реле «Резерв» — Включено | Выход `D4` активен, резерв работает |

Полезно при пусконаладке: если реле показано «Включено», а нагрузка не
сработала — проблема в монтаже или в типе релейного модуля, а не в прошивке.

### 5.2 Настройки

Все настройки в одной форме. **Пустое поле означает «не менять»** — можно
поправить одну выдержку, не трогая остальное. Неверное значение так же
игнорируется, поэтому опечатка ничего не испортит.

| Поле | Что задаёт | Допустимо | По умолчанию |
|---|---|---|---|
| **Webhook URL** | адрес сервера уведомлений | до 220 символов | не задан |
| **Имя устройства** | поле `device` в уведомлении — по нему различают приборы на сервере | латиница, цифры, `_`, `-`; до 31 символа | `Wemos_D1_Pump` |
| **Выдержка аварии, с** | сколько оба основных насоса должны стоять до сигнала | 0…3600 | `5` |
| **Выдержка резерва, с** | сколько резерв должен работать до сигнала | 0…3600 | `0` (сразу) |

Настройки сохраняются в файл во внутренней памяти прибора, переживают
отключение питания и сброс Wi-Fi.

> Если панель показывает красное предупреждение «Файловая система недоступна»,
> настройки работают только до перезагрузки. Причина почти всегда в настройке
> `Flash Size` при прошивке — нужен вариант с файловой системой, не `FS:none`.

> Русские буквы и пробелы в имени устройства **не сохранятся** — они будут
> отброшены. Это не ошибка: ограничение защищает формат уведомления от поломки.
> Пишите, например, `Nasosnaya_1` или `Pump_Station_A`.

**На новом приборе адрес уведомлений не задан** — панель покажет
`не задан - уведомления отключены`, сообщения отправляться не будут, всё
остальное работает.

---

## 6. Уведомления на сервер

При изменении ситуации прибор отправляет сообщение на настроенный адрес:

| Событие | Что означает |
|---|---|
| `MAIN PUMPS` / `ALARM` | Оба основных насоса стоят |
| `MAIN PUMPS` / `OK` | Работа восстановлена |
| `EMERGENCY PUMP` / `STARTED` | Запустился резервный насос |
| `EMERGENCY PUMP` / `STOPPED` | Резервный насос остановился |

Уведомления отправляются один раз на каждое изменение, а не повторяются.
Если в момент события связи не было — уведомление **не будет** отправлено
позже, оно теряется.

На отправку отводится не больше **3 секунд**. Если сервер недоступен или
отвечает медленно, прибор прекращает попытку и продолжает работу: экран и
кнопка на это время замирают, но **выходы аварии срабатывают сразу**, не
дожидаясь сервера.

---

## 7. Сброс настроек Wi-Fi

Нужен при смене роутера или пароля сети. Физической кнопки сброса у прибора нет.

**Если сеть пропала или сменился пароль** — ничего делать не нужно: при
перезагрузке прибор не сможет подключиться и **сам** поднимет точку доступа
`Pump_Control_Set`. Подключитесь к ней и введите новые данные (раздел 3).

**Если надо перевести прибор в другую сеть, а текущая работает** — нажмите
**Сбросить Wi-Fi** на панели мониторинга. Прибор перезагрузится и поднимет точку
доступа.

**Если панель недоступна, а сеть работает** — выключите роутер и перезагрузите
прибор по питанию. Не найдя сеть, он откроет портал настройки.

Настройки из блока «Настройки» (адрес уведомлений, имя устройства, выдержки) при
сбросе Wi-Fi **не стираются**.

---

## 8. Задержки срабатывания

Задержки заданы намеренно, чтобы не срабатывать на кратковременные пуски и
остановки:

| Событие | Задержка |
|---|---|
| Фиксация нового состояния датчика | 3 секунды (не настраивается) |
| Авария основных насосов (после фиксации) | **Выдержка аварии**, по умолчанию 5 с |
| Пуск резерва (после фиксации) | **Выдержка резерва**, по умолчанию 0 с |
| Итого до сигнала аварии при значениях по умолчанию | **~8 секунд** |
| Итого до сигнала о резерве при значениях по умолчанию | ~3 секунды |

Обе выдержки настраиваются в панели (раздел 5.2) и действуют **одновременно на
реле и на уведомление** — отдельно задержать только уведомление нельзя.

Выдержка `0` означает «сразу после фиксации», то есть через те же 3 секунды
антидребезга.

---

## 9. Диагностика

| Симптом | Причина / что делать |
|---|---|
| Экран не горит | Проверьте питание и провода SDA/SCL. Если адрес дисплея `0x3D`, требуется правка прошивки (константа `OLED_ADDR`) |
| Экран горит, но насосы всегда `STOPPED` | Контакты датчиков не замыкаются на `GND`; проверьте общий провод |
| Насосы всегда `RUNNING` | Вход замкнут на `GND` постоянно — проверьте контакт пускателя |
| `WiFi: NO CONNECTION` | Сеть недоступна или сменился пароль → выполните сброс Wi-Fi (раздел 7) |
| Панель в браузере не открывается | Проверьте, что компьютер в той же сети; уточните IP на экране прибора |
| Уведомления не приходят | Проверьте адрес webhook на панели и доступность сервера. Смотрите лог в мониторе порта (115200 бод): `[HTTP] Код: 200` — доставлено; `[HTTP] DNS не ответил` — проблема с именем сервера или DNS роутера; `[HTTP] Ошибка:` — сервер не ответил вовремя |
| Экран замирает на 1-3 с в момент аварии | Так и задумано: отправка уведомления блокирует прибор не дольше 3 секунд. Реле при этом срабатывают сразу, без ожидания сервера |
| Панель пишет «Реле включено», но нагрузка не сработала | Проблема в монтаже или в типе модуля. Проверьте, что модуль **active-LOW**, что он питается, и что общий GND соединён |
| Реле сработали наоборот: включены в норме, отпускают при аварии | Стоит модуль с активным HIGH вместо active-LOW. Замените модуль либо потребуйте правку прошивки |
| Реле щёлкает при заливке прошивки | Нормально: схема автосброса USB дёргает `D3`. На работу не влияет |
| Имя устройства не сохраняется | В нём есть русские буквы, пробелы или знаки препинания — они отбрасываются. Допустимы только латиница, цифры, `_` и `-` |
| Выдержка не сохраняется | Значение вне диапазона 0…3600 или не целое число — поле игнорируется |
| Прибор не стартует после включения | На `D3` или `D4` висит нагрузка, тянущая пин к GND при старте — проверьте релейный модуль и его питание |

Подробный лог работы выводится в USB-порт: скорость **115200 бод**
(Arduino IDE → Инструменты → Монитор порта).

---

## 10. Безопасность

Прибор не имеет пароля на веб-панель. Любой пользователь локальной сети может
открыть панель, сбросить Wi-Fi, изменить адрес уведомлений и **увеличить
выдержки аварии**, то есть замедлить реакцию сигнализации. Устанавливайте прибор
в закрытом технологическом сегменте сети, не в гостевом Wi-Fi.

Контроллер выполняет **функцию мониторинга и сигнализации**, а не защиты.
Он не заменяет штатную автоматику защиты насосной станции. Кроме того, схема не
отказобезопасна: обесточенный контроллер сигнала аварии не подаёт (см. 2.3).