Arduino/pump_controller_8_2_OLED_DONE/MANUAL.md

# Контроллер насосов 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. Экран

```
SUPPLY OK
────────────────────────
P1:RUN  P2:OFF  BK:OFF
ALARM:OFF  BACKUP:OFF
────────────────────────
192.168.1.128
```

**Верхняя строка — главный ответ**, набрана крупно и читается от двери:

| Надпись | Значение |
|---|---|
| `SUPPLY OK` | Норма, подача идёт |
| `BACKUP RUN` | Работает резерв, основные в порядке — обратите внимание |
| `NO SUPPLY` (мигает) | **Авария: оба основных стоят, подачи нет** |
| `BACKUP ON` (мигает) | **Авария: основные стоят, подачу держит резерв** |
| `STARTING` | Идёт запуск, первые ~4 секунды |

Вторая строка — датчики: `RUN` насос работает, `OFF` стоит. `P1` и `P2` —
основные, `BK` — резерв.

Третья строка — что подано на выходы: `ON` реле замкнуто, `OFF` разомкнуто.
Удобно при пусконаладке: видно, что прибор действительно выдал сигнал.

Нижняя строка — адрес в сети или `no network`, если связи нет.

Надписи латиницей: встроенный шрифт дисплея кириллицы не содержит.

---

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

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

Панель устроена как световое табло: **сверху крупно главный ответ**, ниже —
лампы датчиков и выходов, в самом низу свёрнутые настройки.

### 5.1 Главная плашка

| Плашка | Цвет | Что значит |
|---|---|---|
| **Подача есть** | зелёный | Норма, работает хотя бы один основной насос |
| **Работает резерв** | жёлтый | Резерв в работе, основные в порядке — обратите внимание |
| **Насосы стоят** | красный, пульсирует | **Авария: оба основных остановлены** |
| **Запуск** | серый | Первые ~4 секунды после включения |

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

Жёлтый у резерва выбран намеренно: работающий резерв — это предупреждение,
система ещё справляется. Красный оставлен для случая, когда основной подачи нет.

**Вкладка браузера тоже показывает состояние** — в её заголовке текущий статус,
а кружок-значок меняет цвет. Свёрнутую на телефоне вкладку видно, не открывая.

### 5.2 Лампы

Три лампы датчиков: **Насос 1**, **Насос 2**, **Резерв** — «работает», «стоит»
или «ожидание».

Две лампы выходов: **Выход «Авария»** и **Выход «Резерв»** — «замкнут» или
«разомкнут». Это то, что прибор реально подал на реле.

Полезно при пусконаладке: если выход показан замкнутым, а нагрузка не сработала,
проблема в монтаже или в типе релейного модуля, а не в прошивке.

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

Раскрываются по нажатию на строку **Настройки** — в обычной работе они свёрнуты
и не отвлекают.

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

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

Под полем адреса показано только **имя сервера**, а не весь адрес: он содержит
секретный ключ, и выводить его на экран, который видно всем в помещении, не
нужно. Чтобы сменить адрес — введите новый целиком.

Кнопка **Сменить сеть Wi-Fi** стирает сохранённую сеть и перезагружает прибор
(см. раздел 7).

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

> Если панель показывает красное предупреждение «Память недоступна» или
> настройки пропадают после перезагрузки — причина в настройке `Flash Size`
> при прошивке. Она обязана совпадать с фактическим размером памяти платы:
> для этих приборов **`2MB (FS:64KB OTA:~992KB)`**. Вариант `4MB` на плате с
> 2 МБ приводит ровно к такому симптому.

> Русские буквы и пробелы в имени прибора **не сохранятся** — они будут
> отброшены. Это не ошибка: ограничение защищает формат уведомления от поломки.
> Пишите, например, `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.3) и действуют **одновременно на
реле и на уведомление** — отдельно задержать только уведомление нельзя.

Задержка `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).