282 lines
14 KiB
Markdown
282 lines
14 KiB
Markdown
# Настройка ButtonTask на готовом устройстве
|
||
|
||
Инструкция для панели, которая **уже установлена и запущена**. Процесс установки и деплоя здесь не описан.
|
||
|
||
## Исходное состояние
|
||
|
||
| Параметр | Значение по умолчанию |
|
||
|----------|------------------------|
|
||
| IP устройства | `192.168.1.60` (статический, `eth0`) |
|
||
| Веб-конфигуратор | `http://192.168.1.60:8080` |
|
||
| Пароль веба и панели | `admin` |
|
||
| Кнопка на экране | «Вызов клининга» |
|
||
| URL кнопки | `http://192.168.1.55` (адрес сервиса в вашей сети) |
|
||
| Срабатывание | удержание ~800 мс |
|
||
|
||
Убедитесь, что ПК в той же подсети (`192.168.1.x`) и панель отвечает по IP.
|
||
|
||
---
|
||
|
||
## Два способа настройки
|
||
|
||
| Что настраивать | Где удобнее |
|
||
|-----------------|-------------|
|
||
| URL, тексты, иконки, цвет, удержание/клик | Панель **или** веб |
|
||
| **Правила JSON** (расширенная проверка ответа), polling | Только **веб** |
|
||
| Внешний вид (фон, сетка, обводка), сеть, журнал, OTA | Только **веб** |
|
||
| Включить/выключить расширенную проверку (без правил) | Панель (переключатель) + веб (правила) |
|
||
|
||
Изменения из веба и с панели пишутся в один файл `/opt/buttontask/config/config.json` и подхватываются приложением автоматически.
|
||
|
||
---
|
||
|
||
## Веб-конфигуратор
|
||
|
||
### Вход
|
||
|
||
1. Откройте в браузере: **http://192.168.1.60:8080**
|
||
2. Пароль: **admin** (сменить — вкладка «Безопасность»).
|
||
|
||
### Вкладка «Кнопки»
|
||
|
||
Список кнопок. Для каждой: **✎ Редактировать**, **✕ Удалить**. Кнопка **+ Добавить** — новая кнопка.
|
||
|
||
Порядок в списке меняется перетаскиванием (drag-and-drop).
|
||
|
||
#### Диалог редактирования кнопки
|
||
|
||
| Поле | Назначение |
|
||
|------|------------|
|
||
| Подпись | Текст под кнопкой на панели |
|
||
| Иконка | Файл из `/opt/buttontask/icons` (загрузка — вкладка «Внешний вид») |
|
||
| Метод | `GET` или `POST` |
|
||
| URL | Куда уходит запрос, например `http://192.168.1.55/api/call` |
|
||
| Текст успеха | Сообщение при **успехе** (не подставляйте сюда URL) |
|
||
| Текст ошибки | Сообщение при ошибке |
|
||
| Текст ожидания | Пока идёт запрос или polling (`...` по умолчанию) |
|
||
| Цвет кнопки | Цвет круга на панели |
|
||
| Срабатывание | **Удержание** (нужно держать палец) или **Клик** |
|
||
| Длительность удержания | 200–3000 мс |
|
||
|
||
После **Сохранить** страница перезагрузится; на панели изменения видны сразу.
|
||
|
||
---
|
||
|
||
## Простая кнопка (только HTTP)
|
||
|
||
Если галочка **«Расширенная проверка ответа (JSON)»** **выключена**:
|
||
|
||
- успех = HTTP-код **меньше 400** (ответ 200, 201…);
|
||
- ошибка = код 400 и выше или сеть недоступна;
|
||
- тело ответа **не разбирается**.
|
||
|
||
Подходит, когда сервер просто отвечает `200 OK` без важного JSON.
|
||
|
||
**Пример — дефолтная «Вызов клининга»:**
|
||
|
||
- URL: `http://192.168.1.55`
|
||
- Текст успеха: `Вызов отправлен`
|
||
- Текст ошибки: `Ошибка`
|
||
- Расширенная проверка: выкл.
|
||
|
||
---
|
||
|
||
## Расширенная проверка JSON
|
||
|
||
Включите **«Расширенная проверка ответа (JSON)»**, если сервер возвращает JSON и результат нужно понимать по полям в теле, а не только по коду HTTP.
|
||
|
||
### Как это работает на панели
|
||
|
||
1. Нажатие → белая обводка / свечение (**ожидание**).
|
||
2. По правилам:
|
||
- **Принято** → зелёная обводка;
|
||
- **Ошибка** → красная;
|
||
- **Ожидание** → жёлтое пульсирующее свечение, повтор запросов (polling).
|
||
3. Через несколько секунд подпись и обводка гаснут (по умолчанию ~5 с).
|
||
|
||
Пока кнопка занята (статус не «готов»), повторное нажатие блокируется.
|
||
|
||
### Блок настроек в вебе
|
||
|
||
| Параметр | Описание |
|
||
|----------|----------|
|
||
| Требовать HTTP < 400 | При выкл. смотрят только правила JSON, даже если HTTP 500 |
|
||
| Если ни одно правило не подошло | Что делать с неизвестным ответом (обычно **Ошибка**) |
|
||
| **Правила** | Таблица: поле → значение → **результат** → сообщение |
|
||
| Polling | Интервал, макс. попыток, общий таймаут — только для результата **Ожидание** |
|
||
|
||
### Строка правила
|
||
|
||
Колонки (слева направо):
|
||
|
||
1. **Поле** — имя в JSON, точка для вложенности (`data.status`).
|
||
2. **Условие** — «равно» или «содержит».
|
||
3. **Значение** — с чем сравнивать.
|
||
4. **Результат** — **Принято** / **Ошибка** / **Ожидание** ← важнейшая колонка.
|
||
5. **Сообщение** — необязательно; иначе берётся текст успеха/ошибки/ожидания.
|
||
|
||
> **Частая ошибка:** для `success = error` в колонке результата оставили **Принято** — панель станет зелёной с текстом «Сбой». Для ошибки нужно **Ошибка**, для `pending` — **Ожидание**.
|
||
|
||
### Пример: ответ с полем `success`
|
||
|
||
Сервер отвечает: `{"success":"ok"}` / `"pending"` / `"error"`.
|
||
|
||
| поле | равно | результат | сообщение |
|
||
|------|-------|-----------|-----------|
|
||
| `success` | `ok` | Принято | Готово |
|
||
| `success` | `pending` | **Ожидание** | Ждём… |
|
||
| `success` | `error` | **Ошибка** | Сбой |
|
||
|
||
Polling: интервал **2000** мс, попыток **10**, таймаут **60000** мс.
|
||
|
||
### Пример: вложенный JSON
|
||
|
||
URL: `http://сервер/nested?status=ready`
|
||
Ответ: `{"data":{"status":"ready"}}`
|
||
|
||
| поле | равно | результат | сообщение |
|
||
|------|-------|-----------|-----------|
|
||
| `data.status` | `ready` | Принято | Принято |
|
||
| `data.status` | `busy` | Ожидание | Занято |
|
||
| `data.status` | `fail` | Ошибка | Отказ |
|
||
|
||
### Пример: эндпоинт `/state`
|
||
|
||
URL: `http://сервер/state?phase=error`
|
||
В **теле** JSON поле называется `success`, не `phase`:
|
||
|
||
```json
|
||
{"success":"error","ts":...}
|
||
```
|
||
|
||
Правило: поле **`success`**, значение `error`, результат **Ошибка**.
|
||
|
||
### Polling
|
||
|
||
Используйте, когда первые ответы приходят с `"success":"pending"`, а готовность — с `"success":"ok"`.
|
||
|
||
- Каждые `intervalMs` мс повторяется тот же URL.
|
||
- Останавливается при **Принято** / **Ошибка**, по лимиту попыток или таймауту.
|
||
- Перед повторным тестом на тестовом сервере сбросьте счётчик: `GET .../reset`.
|
||
|
||
---
|
||
|
||
## Настройка на самой панели
|
||
|
||
### Открыть настройки
|
||
|
||
1. Нажмите **шестерёнку** (правый нижний угол).
|
||
2. Введите пароль (**admin** по умолчанию).
|
||
|
||
### Разделы меню
|
||
|
||
| Раздел | Возможности |
|
||
|--------|-------------|
|
||
| **Кнопки** | Список, добавить, редактировать, удалить, порядок (≡ перетащить) |
|
||
| **Расположение** | Сетка / список, число колонок, отступы, подписи |
|
||
| **Фон** | Градиент, цвет, картинка |
|
||
| **Обводка** | Цвета и толщина OK/ошибка, свечение |
|
||
| **Сеть** | Просмотр интерфейсов; смена IP — удобнее в вебе |
|
||
| **Обновление** | Текущая версия ПО (OTA — в основном через веб) |
|
||
| **Сменить пароль** | Пароль для панели и веба |
|
||
|
||
### Редактор кнопки на панели
|
||
|
||
Те же поля, что в вебе: подпись, иконка, метод, URL, тексты, цвет, удержание/клик.
|
||
|
||
Переключатель **«Расширенная проверка»** только включает/выключает режим. **Правила JSON задаются в веб-конфигураторе** (подсказка на экране).
|
||
|
||
### Нажатие кнопки на панели
|
||
|
||
- **Удержание** (по умолчанию): удерживайте, пока заполнится кольцо (~800 мс), затем отпустите — уйдёт запрос.
|
||
- **Клик**: одно касание.
|
||
|
||
---
|
||
|
||
## Вкладки веба (кратко)
|
||
|
||
### Внешний вид
|
||
|
||
- **Расположение** — сетка/список, колонки, отступы.
|
||
- **Фон** — тип, цвета, анимация, фоновое изображение.
|
||
- **Обводка** — цвета OK/ERR, толщина, радиус свечения.
|
||
- **Иконки** — загрузка PNG/JPG/SVG в папку иконок.
|
||
|
||
### Сеть
|
||
|
||
Состояние `eth0`, режим DHCP/статический IP, шлюз, DNS. После **Применить** настройки сохраняются в `network.json` и применяются скриптом сети.
|
||
|
||
### Система
|
||
|
||
- Нагрузка CPU/RAM, время.
|
||
- Доступ: ping (ICMP), SSH, порт веба.
|
||
- **Журнал нажатий** — какая кнопка, URL, результат (`OK` / `ERR` / `WAIT`), время в мс.
|
||
|
||
Полезно при отладке: если везде `OK 200` без `WAIT`, проверьте колонку **результат** в правилах.
|
||
|
||
### Обновление
|
||
|
||
Загрузка пакета `.tar.gz` (бинарник + веб). Конфиг и иконки в `/opt/buttontask/config` и `icons` **не затираются**.
|
||
|
||
### Безопасность
|
||
|
||
Смена пароля веба и панели.
|
||
|
||
---
|
||
|
||
## Проверка с ПК (необязательно)
|
||
|
||
Для отладки HTTP без реального сервиса на другой машине в сети:
|
||
|
||
```bash
|
||
python3 tools/button-test-server.py --host 0.0.0.0 --port 8765
|
||
```
|
||
|
||
Примеры URL для кнопки:
|
||
|
||
| URL | Поведение |
|
||
|-----|-----------|
|
||
| `http://<IP-ПК>:8765/ok` | Простой HTTP 200 |
|
||
| `http://<IP-ПК>:8765/state?phase=error` | JSON `success: error` |
|
||
| `http://<IP-ПК>:8765/poll?pending=3` | 3× pending, затем ok |
|
||
| `http://<IP-ПК>:8765/nested?status=ready` | Вложенное поле `data.status` |
|
||
|
||
На Windows откройте порт 8765 в брандмауэре. Перед тестом poll: `http://<IP-ПК>:8765/reset`.
|
||
|
||
---
|
||
|
||
## Типичные проблемы
|
||
|
||
| Симптом | Причина | Что сделать |
|
||
|---------|---------|-------------|
|
||
| Всегда зелёный, один запрос | Правила с результатом **Принято** для всех значений | Исправить колонку «результат» |
|
||
| Сообщение = URL кнопки | URL попал в «Текст успеха» | Вписать нормальный текст |
|
||
| Polling не идёт | Для `pending` стоит результат **Принято** | Поставить **Ожидание** |
|
||
| `phase=error`, а правило не срабатывает | В JSON поле `success`, не `phase` | Правило по полю `success` |
|
||
| Веб не открывается | Неверный IP / порт / firewall | Проверить `192.168.1.60:8080`, вкладка «Сеть» |
|
||
| Настройки не видны на панели | Не сохранили в вебе | Нажать **Сохранить** в диалоге кнопки |
|
||
|
||
### Просмотр конфига на устройстве (SSH)
|
||
|
||
```bash
|
||
sudo cat /opt/buttontask/config/config.json
|
||
```
|
||
|
||
Проверка последнего нажатия:
|
||
|
||
```bash
|
||
tail -1 /opt/buttontask/run/button-log.jsonl | python3 -m json.tool
|
||
```
|
||
|
||
Ожидаемые поля при работающей расширенной проверке: `"outcome": "ok"` / `"error"` / `"pending"`, при простом HTTP — `"outcome": "http"`.
|
||
|
||
---
|
||
|
||
## Минимальный чеклист для новой кнопки
|
||
|
||
1. [ ] URL сервиса доступен с панели (`ping`, HTTP).
|
||
2. [ ] Тексты успеха/ошибки/ожидания заполнены осмысленно.
|
||
3. [ ] Если нужен JSON — включена расширенная проверка, добавлены правила с **правильным результатом**.
|
||
4. [ ] Для долгих операций — правило **Ожидание** + блок polling.
|
||
5. [ ] Проверка на панели + запись в журнале на вкладке «Система».
|