Skip to content

Быстрый старт

Прошить плату с нуля и поднять её до рабочего состояния — за 10 минут.

Что понадобится

  • Плата NodeMCU v1.0 (ESP8266), WROOM-32 DevKit V1 (ESP32) или ESP-01S (минимальный вариант). Подробнее в Поддерживаемые платы.
  • USB-кабель «micro-USB ↔ ноутбук» — обязательно дата-кабель, не зарядный.
  • Компьютер с Python ≥ 3.10 для запуска PlatformIO.

ESP-01S — без USB на борту

У ESP-01S нет USB-UART chip'а на плате — для прошивки нужен внешний программатор. Программаторы бывают разные: специализированные DIP под ESP-01, универсальные USB-TTL (CH340/CP2102), или другая ESP-плата как мост. Полный гайд: Прошивка через программатор.

1. Установить PlatformIO

pip install platformio
pio device list   # проверить что плата видна по USB

В списке должна быть строка вида /dev/ttyUSB0 или COM3 с описанием CP2102 / CH340 / CP210x (производитель USB-UART моста на плате).

Linux: разрешения на /dev/ttyUSB0

Если pio device list показывает плату, но pio run -t upload падает с Permission denied, добавьте себя в группу dialout: 

sudo usermod -aG dialout $USER
# требуется перелогин

2. Клонировать репозиторий

git clone https://github.com/kavlevru/ctrl-board.git
cd ctrl-board

3. Прошить firmware и filesystem

Плата требует двух образов: сам код (firmware.bin) и файловая система (littlefs.bin — это data/ папка, в которой лежит весь web-UI и дефолты конфигов).

pio run -t upload      # код
pio run -t uploadfs    # data → LittleFS (UI + конфиги)

pio run -e esp32dev -t upload
pio run -e esp32dev -t uploadfs

Требует внешний программатор и перемычку GPIO0→GND во время прошивки. Без web-UI — управление только через REST API:

pio run -e esp01s -t upload --upload-port /dev/ttyUSB0
# передёрни USB (с перемычкой) — нужен повторный bootmode
pio run -e esp01s -t uploadfs --upload-port /dev/ttyUSB0
# сними перемычку, передёрни USB — плата стартует

На свежей плате нужны ОБА

Только upload без uploadfs оставит плату нерабочей: не будет UI, формы настройки Wi-Fi и admin-пользователя. После первой прошивки uploadfs нужно делать только при правках под data/.

Для ESP-01S — UI отсутствует by design, но uploadfs всё равно нужен на первой прошивке (там минимальный /config с дефолтным пользователем и enabled-плагинами).

4. Подключить плату к Wi-Fi

После прошивки и перезагрузки плата ждёт настройку:

  1. С телефона/ноутбука подключиться к открытой Wi-Fi сети CtrlBoard-Setup.
  2. Открыть в браузере http://192.168.4.1 — попадёте на форму настройки.
  3. Ввести SSID и пароль своей домашней сети → «Сохранить и перезагрузить».
  4. Плата подключится в STA-режиме. IP можно увидеть в Serial-мониторе (pio device monitor, baud 115200), в роутере, или просто перебором.
  5. Открыть http://<ip-платы>/ — вы на главной.
  1. С телефона/ноутбука подключиться к AP CtrlBoard-Setup-<суффикс> (имя видно в Serial-логе).
  2. На этом AP плата — 192.168.4.1. В AP-mode endpoint POST /api/v1/settings/wifi bypass'ит auth — провизионить можно без логина: 
    curl -X POST http://192.168.4.1/api/v1/settings/wifi \
  -H 'Content-Type: application/json' \
  -d '{"wifi_networks":[{"ssid":"YourSSID","password":"YourPass"}]}'
  3. Плата перезагрузится в STA-режиме. IP найди в роутере или Serial-логе.
  4. Дальше работаешь через REST API. Базовый login: 
    curl -X POST http://<ip>/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"1234"}'
# → access_token используешь как Bearer для остальных запросов

5. Залогиниться

Дефолтные креды:

admin / 1234

Сразу зайдите в Настройки → Пользователи и поменяйте пароль.

Опционально: отключить вход целиком

Для домашней LAN, защищённой Wi-Fi паролем, форма логина — лишняя. Открыть Настройки → Авторизация → Требовать вход = off. Теперь UI работает без токена.

Не делайте этого если плата как-то доступна снаружи (порт-форвардинг, VPN с широким доступом).

6. Привязать к облаку (опционально)

Если нужен доступ к плате извне или OTA по кнопке через cloud.kavlev.ru/:

  1. Зарегистрироваться на https://cloud.kavlev.ru/ — логин по email + одноразовый код.
  2. Создать проект в облачном кабинете → скопировать project_api_key.
  3. В UI платы открыть Облако в верхнем меню → ввести URL https://cloud.kavlev.ru/ + ключ → сохранить.
  4. Через 15–30 секунд плата появится на дашборде проекта.

Дальше — см. Облачный сервис для команд, OTA и расшаривания.

Что дальше