Подключение к Марусе — пошагово¶

Инструкция для пользователя: как привязать плату Kavlev к голосовому ассистенту Маруся (VK).

После этой настройки команды вроде «Маруся, включи свет на кухне» или «Маруся, какая температура в спальне» будут работать.

1. Скачать прошивку¶

Открываем kavlev.ru → Скачать прошивку.

Для вашей платы качаем два файла:

firmware-<version>.bin — прошивка
littlefs-<version>.bin — файловая система (UI + начальные конфиги)

Поддерживаемые платы:

Платa	Где используется
NodeMCU v1.0 (ESP8266)	базовый вариант — 1-4 устройства, до 10 датчиков
WROOM-32 (ESP32)	расширенный вариант — больше памяти, RMT для ИК
ESP-01S	компактный для встройки в подрозетник, только реле + API (без UI)

2. Прошить плату¶

Подробная инструкция: Прошивка через программатор (для UART/USB-flash также подойдёт PlatformIO pio run -t upload).

Кратко: подключаем плату по USB → flasher tool (PlatformIO / esptool / web-flasher) → заливаем оба файла → плата перезагружается → создаёт AP CtrlBoard-Setup-XXXXXXXX (где XXXXXXXX — 8 hex-символов из UUID платы, чтобы две заводские платы рядом не светили одинаковое имя).

ESP-01S без UI

На ESP-01S веб-интерфейс отключён (build flag NO_WEB_UI — экономия Flash). Конфигурация выполняется через REST API напрямую — см. API-рецепты. Остальные шаги аналогичны.

3. Подключить устройства и настроить плату (ESP8266 / ESP32)¶

С телефона / ноутбука присоединяемся к AP CtrlBoard-Setup-XXXXXXXX → открывается UI платы по адресу 192.168.4.1.

Настройки → Wi-Fi: вводим SSID/пароль домашней сети, плата переподключается в неё
Устройства: добавляем реле, датчики, кнопки на соответствующие пины платы — подробнее
(Опционально) Задачи: расписания, mesh-триггеры, сценарии — подробнее

После этого плата уже работает локально — без облака. Дальнейшие шаги нужны только для голосового управления.

4. Привязать плату к облаку¶

Регистрируемся / входим на cloud.kavlev.ru.

Создаём проект (если ещё нет)
+Добавить плату — копируем UUID платы из её UI (Настройки → Облако → UUID)
На плате: Настройки → Облако → вставляем endpoint cloud.kavlev.ru и токен из cloud-кабинета → Save

Плата начинает heartbeat в облако каждые 30 секунд — статус в cloud.kavlev.ru становится «online».

Подробный гайд по UI облака.

5. Настроить типы устройств для голосового ассистента¶

В облачном кабинете → Интеграции → для каждого устройства выбираем тип для голосового ассистента:

Реле «лампа в коридоре» → тип Свет
Реле «кондей» → тип Кондиционер (требует ИК-модуля на плате)
DS18B20 «датчик в спальне» → тип Климатический датчик (температура)
Кнопка → Кнопка (для триггеров сценариев)

См. полный список совместимых устройств ниже.

6. Сопряжение в приложении Маруся¶

В приложении Маруся (VK) на телефоне:

Умный дом → Добавить устройство
В списке производителей выбираем Kavlev
Логин/пароль от cloud.kavlev.ru
Разрешить доступ Марусе

Маруся подтянет все устройства из вашего проекта с заполненными типами. Готово.

7. Проверяем голосом¶

«Маруся, включи свет в коридоре»
«Маруся, выключи кондиционер»
«Маруся, какая температура в спальне»
«Маруся, открой шторы»

Совместимые устройства¶

Маруся видит устройства Kavlev как стандартные типы Smart Home API. Что поддерживается:

Управляемые (реле / выключатели)¶

Тип в Марусе	Голосовые команды	Что подключаем
Свет (`light`)	«включи свет», «выключи свет»	реле + лампа / световая линия
Розетка (`socket`)	«включи розетку», «выключи розетку»	реле на любой бытовой прибор
Шторы (`openable.curtain`)	«открой шторы», «закрой шторы»	реле управления приводом штор
Клапан (`openable.valve`)	«открой воду», «закрой газ»	реле на сервопривод или соленоид
Выключатель (`switch`)	«включи/выключи <имя>»	универсальная команда on/off
Кондиционер (`thermostat.ac`)	«включи кондей», «выключи кондей»	требует ИК-модуля (только ESP32) — подробнее в гайде по ИК
Прочее (`other`)	«включи/выключи <имя>»	если ни один из специфичных типов не подходит

Датчики (только чтение состояния)¶

Тип в Марусе	Что докладывает	Совместимые сенсоры
Климат (`sensor.climate`)	температура, влажность, давление	DS18B20, DHT22, BME280
Расстояние (`sensor`)	сантиметры до объекта	HC-SR04 (ультразвук)
Водомер (`sensor` + water_meter)	м³ воды	импульсный счётчик (pulse_counter)
Открытие (`sensor.open`)	открыто / закрыто	геркон, концевик, digital_input
Кнопка (`sensor.button`)	нажата (триггер)	физическая кнопка → событие

Чего пока нет¶

Диммирование света (только on/off на реле)
Цветные RGB-лампы
Управление ТВ / медиа
Чайник / кофеварка (физически реле может, но cooking.* типы в маппере не настроены — открываем по запросу)

Если нужного типа нет — пишите на contact@kavlev.ru, добавим в следующем релизе cloud-service.

Технические детали (для разработчиков, OAuth-привязка, push-обновления) — интеграция Маруся: технический гайд.