# Настройка с дисплея и кнопки

Мастер настройки работает прямо на репитере: не нужен ни компьютер, ни телефон. Он доступен на любой плате, у которой есть дисплей и кнопка, и отсутствует на платах без дисплея — там настройка выполняется через [последовательный CLI](./custom-cli.md) или [веб-панель](./web-panel.md).

Та же страница с теми же иллюстрациями есть в вики проекта: <https://git.meshinfo.ru/shade/MeshCore-Posadmesh/wiki/Device-Setup>.

![Схема управления и переходов](_assets/wizard/12-controls.png)

## Как войти и выйти

| Действие | Результат |
| --- | --- |
| Двойное нажатие на экране состояния | вход в мастер (меню `Setup`) |
| Длинное нажатие на экране состояния | выключение питания узла |
| Пункт `Save & exit` внизу меню | выход из мастера, радиопараметры применяются |

Если узел прошит «с нуля» и ещё не имеет имени, мастер открывается сам после заставки.

| Экран состояния | Меню, начало списка | Меню, радиопункты и выход |
| --- | --- | --- |
| ![Экран состояния](_assets/wizard/01-status.png) | ![Меню Setup](_assets/wizard/02-menu-top.png) | ![Низ меню](_assets/wizard/03-menu-bottom.png) |

## Что настраивается

Мастер меняет только то, что нужно для быстрого ввода узла в сеть:

| Пункт меню | Что делает | Команда CLI |
| --- | --- | --- |
| `Coordinates` | широта и долгота узла | `set lat`, `set lon` |
| `Frequency` | частота: целые МГц шагом 1, кГц — по разрядам | `set radio` |
| `Bandwidth` | полоса, поразрядно | `set radio` |
| `CR` | coding rate, 5–8 | `set radio` |
| `SF` | spreading factor, 5–12 | `set radio` |
| `TX power` | мощность передатчика, 1–30 дБм | `set tx` |
| `Battery` | напряжение, процент заряда и текущий множитель ADC — только просмотр | `get battery`, `get adc.multiplier` |
| `ADC` | множитель ADC для калибровки измерения батареи: открывается с заводского значения платы (Heltec V4 — 5.420, Meshadventurer — 2.000), `0.000` возвращает заводское | `set adc.multiplier` |
| `Repeat` | пересылка пакетов включена или выключена | `set repeat` |
| `Path hash` | размер хэша пути: 0, 1 или 2 байта | `set path.hash.mode` |
| `Advert int` | интервал advert в минутах (0 — выключено, иначе 60–240) | `set advert.interval` |
| `Flood advert` | интервал flood advert в часах (3–168) | `set flood.advert.interval` |
| `Flood max` | лимит пересылки flood (0–64) | `set flood.max` |
| `Save & exit` | выход из мастера | — |

Значения применяются сразу при выходе из пункта и сохраняются во флеш. Ответ устройства (`OK` или текст ошибки) показывается на экране — проверку выполняет тот же код, что и последовательный CLI, поэтому неверное значение не будет записано.

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

Экран состояния (обычный режим):

- **короткое** — включить или продлить подсветку экрана;
- **двойное** — войти в мастер настройки;
- **длинное** — выключить питание узла.

В меню:

- **короткое** — следующий пункт, **двойное** — предыдущий;
- **длинное** — войти в пункт.

В пункте с числом или списком:

- **короткое** — увеличить значение, **двойное** — уменьшить;
- **длинное** — применить и вернуться в меню.

Если узел прошит «с нуля» и ещё не имеет имени, мастер открывается сам после заставки.

## Ввод координат

Координаты показываются в формате `xx.xxxx yy.yyyy` — сначала широта, затем долгота. Активная цифра выделена инверсией.

| Действие | Что происходит |
| --- | --- |
| длинное нажатие | войти в изменение текущей цифры |
| короткое нажатие в режиме правки | цифра +1 |
| двойное нажатие в режиме правки | цифра −1 |
| длинное нажатие в режиме правки | применить цифру |
| короткое нажатие после применения | перейти к следующей цифре |
| длинное нажатие на экране `Save & exit?` | сохранить координаты и выйти |
| двойное нажатие на экране `Save & exit?` | вернуться к правке |

Всего перебираются 12 цифр: шесть для широты и шесть для долготы. Когда применены все, короткое нажатие выводит экран подтверждения. Координаты сохраняются двумя командами — `set lat` и `set lon`; после сохранения узел появится на карте MeshCoreTel в течение следующего advert.

| Правка разряда широты | Подтверждение сохранения |
| --- | --- |
| ![Координаты](_assets/wizard/09-coordinates.png) | ![Сохранение координат](_assets/wizard/10-coordinates-save.png) |

Ограничение: мастер вводит положительные координаты (формат без знака). Для южного полушария и западной долготы используйте CLI (`set lat -33.1234`) или веб-панель.

## Ввод частоты и полосы

Частота показывается как `868.731 MHz`, полоса — как `062.50 kHz`. Под значением расположен пункт `Save & exit`, курсор ходит по всем позициям экрана.

Частота, позиции по порядку:

- **целые МГц** (выделены целиком): короткое нажатие — `+1 МГц`, двойное — `−1 МГц`;
- **три разряда кГц** по отдельности: короткое нажатие — `+1`, двойное — `−1`, принцип тот же, что у координат;
- **`Save & exit`** — сохранение частоты и возврат в меню.

Порядок работы: длинное нажатие входит в правку позиции, короткое и двойное меняют значение, длинное применяет позицию, а короткое после применения переводит курсор к следующей позиции. Когда все цифры поправлены, перейдите короткими нажатиями на `Save & exit` и удерживайте кнопку — частота применится, и экран вернётся в меню.

Полоса вводится так же поразрядно и с тем же пунктом `Save & exit` внизу.

| Выбраны целые МГц | Правка разряда кГц | Ответ устройства на экране |
| --- | --- | --- |
| ![Экран частоты](_assets/wizard/04-freq.png) | ![Правка разряда](_assets/wizard/05-freq-edit.png) | ![Ответ OK](_assets/wizard/11-toast-ok.png) |

`CR` и `SF` меняются шагом: короткое нажатие — `+1`, двойное — `−1`, длинное — применить.

| Полоса | CR | SF |
| --- | --- | --- |
| ![Экран полосы](_assets/wizard/06-bandwidth.png) | ![CR](_assets/wizard/07-cr.png) | ![SF](_assets/wizard/08-sf.png) |

Любой из четырёх пунктов отправляет команду целиком — `set radio <частота>,<полоса>,<sf>,<cr>`, поэтому остальные три параметра сохраняют свои значения. Устройство отвечает `OK - reboot to apply`: изменения радио вступают в силу после перезагрузки.

## Батарея и калибровка ADC

Пункт `Battery` показывает напряжение в вольтах, процент заряда и полоску, а также текущий множитель ADC. Значения обновляются раз в секунду.

| Экран батареи | Правка множителя ADC |
| --- | --- |
| ![Батарея](_assets/wizard/13-battery.png) | ![ADC](_assets/wizard/14-adc.png) |

- **короткое** нажатие — показать «сырое» значение АЦП в милливольтах (удобно сверять с мультиметром);
- **длинное** или **двойное** — вернуться в меню.

Процент берётся у платы, если она умеет его считать (например T-Beam с PMU). Если не умеет — считается линейно по напряжению между `getBatteryMinMilliVolts()` и `getBatteryMaxMilliVolts()` платы; на большинстве плат это 3000–4200 мВ.

Пункт `ADC` правит множитель ADC поразрядно, формат `x.xxx` — так же, как полоса: длинное нажатие входит в правку разряда, короткое `+1`, двойное `−1`, длинное применяет разряд, короткое после применения переходит к следующему разряду, а на пункте `Save & exit` длинное нажатие сохраняет значение и возвращает в меню. Под цифрами видно измеренное напряжение, поэтому калибровать удобно прямо на экране: подстроили множитель — сразу видите новое напряжение.

Поле открывается **не с нуля, а с действующего значения платы**: у Heltec V4 это `5.420`, у Meshadventurer — `2.000`. Так видно, от чего отсчитывается коррекция, и не нужно угадывать заводское число. `0.000` означает «вернуть заводское значение платы»: команда `set adc.multiplier 0` сбрасывает подстройку. Значение применяется командой `set adc.multiplier <x.xxx>` — той же, что и в последовательном CLI.

Коррекция доступна на всех платах, которые измеряют батарею через ADC: механизм живёт в базовом классе `ESP32Board` (`adcMultiplierBase()` + `adcMultiplier()`), платы со своей формулой переведены на него. Платы, у которых батарея измеряется не через ADC (Station G2/G3, T-Beam с PMU), честно сообщают, что подстройка не поддерживается — команда вернёт `Error: unsupported`.

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

## Экран загрузки

При включении узел показывает логотип, ссылку на базовый проект, версию прошивки с датой сборки и адрес проекта:

![Экран загрузки](_assets/wizard/16-boot.png)

Версия — это база upstream и дата сборки (`v1.18.0 (15 Oct 2026)`), адрес `posadmesh.ru` ведёт на сайт проекта.

## Всплывающие сообщения

Ответ устройства на любую команду показывается отдельным окном поверх экрана: рамка, свой фон, текст с переносом строк и кнопка `OK`. Окно модальное — пока оно открыто, экран под ним не меняется, а **короткое нажатие кнопки закрывает его**. Так видно и успешные ответы (например `OK - reboot to apply` после правки радио), и ошибки проверки значений.

![Всплывающее окно с ответом устройства](_assets/wizard/15-popup.png)

Признак успеха: после правки частоты, полосы, `CR` или `SF` окно показывает `OK - reboot to apply` — изменения радио вступают в силу после перезагрузки узла. Если в ответе ошибка (например значение вне диапазона), окно покажет её текст, а настройка не сохранится.

## Ограничения

- На экранах без кириллицы подписи меню выводятся латиницей.
- Мастер не настраивает Wi-Fi, MQTT, регионы и список доступа: для них нужен последовательный CLI или веб-панель. На плате с Wi-Fi их удобнее задавать из веб-панели.
- Если дисплея нет, мастер не компилируется в прошивку и на поведение узла не влияет.