Skip to content

Техническое описание архитектуры

Системное техническое описание архитектуры ПО Room Controller «ОКА» (OZLocks)

1. Назначение системы и общие принципы архитектуры

Программное обеспечение комнатного контроллера «ОКА» (на базе SoC ESP32-S3) предназначено для обеспечения автономной и сетевой автоматизации гостиничных номеров (управление освещением, климатом, обработка сигналов безопасности и интеграция с замковыми системами).

Архитектура ПО построена на трех фундаментальных принципах: 1. Строгая аппаратная изоляция (Core Asymmetry): Критические функции жизнеобеспечения номера изолированы от сетевого стека и кастомной логики сторонних интеграторов. 2. Детерминизм реального времени: Обработка физических портов ввода-вывода выполняется с фиксированными приоритетами под управлением FreeRTOS. 3. Безопасная «песочница» (Sandboxing): Выполнение пользовательских сценариев автоматизации не имеет прямого доступа к памяти и оборудованию, а взаимодействует с системой исключительно через изолированную карту разделяемых регистров.

2. Высокоуровневая слоевая архитектура (System Overview)

Программный стек разделен на независимые горизонтальные слои с жестко регламентированными интерфейсами межслойного взаимодействия (API и Шина событий).

flowchart TB
    subgraph APP["1. Application Layer (Бизнес-логика)"]
        OZFW["OZLock Firmware (Монолит ядра)"]
        SCRIPT["Script Engine (Интерпретатор скриптов)"]
    end

    subgraph MID["2. Middleware (Интеграции и Протоколы)"]
        TCP["TCP/IP Stack + Secure OTA"]
        MODBUS["Modbus Engine (Master/Slave)"]
        EXT["ESPHome / OpenPLC Runtime (Задачи интегратора)"]
        EVBUS["Event Bus & Shared Memory (Шина обмена)"]
    end

    subgraph HAL["3. HAL & Drivers (Абстракция железа)"]
        SPI["SPI Driver (W5500)"]
        I2C["I2C Driver (PCA9535, DS2482S)"]
        UART["UART Driver (RS-485 #1/#2)"]
        ONEWIRE["1-Wire Driver"]
        GPIO_DRV["GPIO Driver (ULN2003, Реле)"]
    end

    subgraph RTOS["4. OS Kernel"]
        KERNEL["FreeRTOS Core (Задачи / Мьютексы / Очереди)"]
    end

    subgraph SEC["5. Security Layer (Сквозной слой)"]
        AUTH["Firmware Signing & OTA Validation"]
        SANDBOX["Sandbox Policy"]
    end

    APP --> EVBUS
    EXT --> EVBUS
    EVBUS --> MID
    MID --> HAL
    HAL --> RTOS
    SEC -.-> APP
    SEC -.-> MID

Описание слоев ПО:

  • Application Layer: Содержит проприетарное ядро OZLocks (обработка гостиничной логики, статусы номеров) и изолированный движок выполнения сценариев Script Engine.
  • Middleware Layer: Управляет коммуникациями. Включает сетевой стек, Modbus-движок для связи с сервером «Аура» и сторонним оборудованием, а также виртуальные рантаймы (OpenPLC/ESPHome) для сторонних интеграторов. Обмен данными идет через атомарную шину событий (Event Bus).
  • HAL & Drivers Layer: Абстрагирует физическую периферию. Отвечает за инициализацию и обслуживание драйверов SPI, I2C, UART и 1-Wire.
  • OS Kernel Layer: Базовое ядро FreeRTOS, распределяющее кванты времени процессора, управляющее очередями сообщений и мьютексами.
  • Security Layer: Сквозной модуль контроля целостности прошивки (подписи) и разграничения прав доступа к памяти.

3. Распределение слоёв и задач по ядрам процессора (Runtime Architecture)

Процессор ESP32-S3 имеет два ядра. Распределение задач выполнено в режиме жесткой привязки (Task Affinity), что исключает влияние сетевых задержек на физическую автоматизацию номера.

flowchart LR
    subgraph CORE0["ESP32-S3 Core 0 (Инфраструктура и Интеграции)"]
        NET["Task_OTA_&_Network (Приоритет: Средний)"]
        ESPHOME["Task_ESPHome_Engine (Приоритет: Низкий)"]
        PLC["Task_ThirdParty_PLC (Приоритет: Низкий)"]
    end

    subgraph CORE1["ESP32-S3 Core 1 (Trusted Real-Time Core)"]
        FW["Task_OZLock_Firmware (Приоритет: Высокий)"]
        IO["Task_Peripheral_IO (Приоритет: Критический)"]
        SLAVE["Task_Modbus_Slave (Приоритет: Средний)"]
    end

    subgraph WD["Служба Watchdog (Иерархия контроля)"]
        HWD["Аппаратный WDT (Защита всей ОС)"]
        SWD["Программный WDT (Контроль Script Engine)"]
    end

    CLOUD["Aura Server (Secure OTA)"]
    HA["Home Assistant / Web API"]
    FIELD_EXT["Сторонняя логика (OpenPLC)"]

    CLOUD -->|Signed Firmware / AST| NET
    HA --> ESPHOME
    FIELD_EXT --> PLC

    IO -->|Потокобезопасная очередь| FW
    SLAVE -->|Мьютекс| FW
    FW -.-> SWD
    KERNEL -.-> HWD

Спецификация задач Core 1 (Выделенное доверенное ядро):

  • Task_Peripheral_IO (Критический приоритет): Циклический опрос расширителей ввода-вывода по I2C, чтение АЦП, работа с 1-Wire. Период квантования — 1-5 мс.
  • Task_OZLock_Firmware (Высокий приоритет): Основной конечный автомат (FSM) контроллера. Обрабатывает логику гостиничных номеров, аварийные сигналы (кнопка SOS, пожарная тревога).
  • Task_Modbus_Slave (Средний приоритет): Обработка запросов от сервера верхнего уровня («Аура») по изолированному каналу RS-485.

Спецификация задач Core 0 (Сетевое ядро и Среда Интеграторов):

  • Task_OTA_&_Network (Средний приоритет): Обслуживание Ethernet-контроллера W5500, удержание TCP-сессий, прием зашифрованных бинарных файлов обновлений.
  • Task_ESPHome_Engine / Task_ThirdParty_PLC (Низкий приоритет): Выделенный квант времени для работы кода сторонних интеграторов. Ограничен по ресурсам процессора, чтобы исключить перегрев или зависание ядра.

4. Архитектура потоков данных и управление памятью (Data Flow & Memory View)

flowchart LR
    subgraph FIELD["Периферия номера"]
        DI["Датчики сухих контактов (DI0-DI7)"]
        AI["Аналоговые входы (AI0-AI3)"]
        OW["Датчики 1-Wire (Температура)"]
        MB["Сторонние устройства (Modbus Master #2)"]
    end

    subgraph CTRL["Архитектура памяти контроллера"]
        subgraph SRAM["SRAM (Быстрая память)"]
            IO_PROC["Peripheral IO Task"]
            EV_BUS["Шина событий (Event Bus)"]
        end
        subgraph PSRAM["8MB PSRAM (Внешняя память)"]
            REG_MAP["Shared Register Map (API обмена)"]
            VM_RESRC["Ресурсы Script Engine & Среды выполнения"]
        end
    end

    subgraph RUNTIME["Движки логики"]
        FW["OZLock Firmware Core"]
        SCRIPT["Script Engine Sandbox"]
    end

    subgraph CLOUD["Верхний уровень"]
        PMS["ПО Аура (Modbus Slave #1)"]
        OTA["Сервер обновлений"]
    end

    DI -->|I2C / Прерывание| IO_PROC
    AI -->|АЦП| IO_PROC
    OW -->|DS2482S| IO_PROC
    MB -->|UART| IO_PROC

    IO_PROC -->|Нормализация событий| EV_BUS
    EV_BUS -->|Атомарная запись| REG_MAP

    REG_MAP <-->|Защищено мьютексом| FW
    REG_MAP -->|Ограниченный API Sandbox| SCRIPT

    FW <-->|RS-485 #1| PMS
    OTA -->|Валидация подписи| FW

Модель распределения памяти:

  1. Внутренняя SRAM (Static Allocation): Размещаются стек ядра ОС, критические очереди прерываний, DMA-буферы для SPI и UART. Динамическое выделение памяти (malloc) в SRAM в процессе работы запрещено.
  2. Внешняя 8MB PSRAM (Dynamic Allocation): Хранит карту разделяемых регистров (Shared Register Map), структуры данных виртуальной машины Script Engine, буферы логов и контекст выполнения сред ESPHome/OpenPLC.

5. Функциональные блоки драйверов и карта интерфейсов (Hardware Mapping)

Топология межкомпонентных шин спроектирована с учетом минимизации использования дефицитных нативных GPIO процессора ESP32-S3 за счет применения специализированных мостов и расширителей шин.

flowchart TD
    subgraph SoC["ESP32-S3 Core MCU"]
        I2C_MAIN["I2C Master Interface"]
        SPI_MAIN["SPI Master Interface"]
        UART_1["UART 1 Порт"]
        UART_2["UART 2 Порт"]
        ADC_INT["Встроенный АЦП"]
        GPIO_INT["Собственные GPIO"]
    end

    subgraph BUS_I2C["Шина I2C"]
        PCA["PCA9535 (16-bit IO Expander)"]
        DS2482["DS2482S-100 (1-Wire Bridge)"]
    end

    subgraph BUS_SPI["Шина SPI"]
        W5500["Wiznet W5500 (Ethernet Controller)"]
    end

    SoC -->|I2C| BUS_I2C
    SoC -->|SPI| BUS_SPI
    SoC -->|UART 1| ISO1["Цифровой изолятор + SN75176"] -->|RS-485 #1| PMS_BUS["Внешняя сеть отеля (Modbus Slave)"]
    SoC -->|UART 2| SN2["SN75176 (Без изоляции)"] -->|RS-485 #2| EXT_BUS["Датчики WirenBoard / Шлюзы Daikin"]

    PCA -->|8х Входов| OPT["Оптическая изоляция"] -->|Входы номера| DI_PINS["Кнопка SOS, Датчик 60G, Герконы"]
    PCA -->|4х Выхода| OD_PINS["Открытый дренаж (DO0-DO3)"]

    SoC -->|GPIO| ULN["ULN2003ADR (Транзисторная сборка)"] -->|Реле питания| RELAYS["Звонок, Контактор номера"]
    SoC -->|ADC| MCP["MCP6004T (ОУ Буфер/Усилитель)"] -->|Аналоговые шины| AI_PINS["Аналоговые датчики AI0-AI3"]
    DS2482 -->|1-Wire| TSENS["Датчики температуры в комнатах"]

Спецификация драйверов:

  • Драйвер I2C (PCA9535 & DS2482S): Опрос чипа PCA9535 настроен по аппаратному прерыванию GPIO контроллера, что избавляет шину от постоянного холостого сканирования. Драйвер шины 1-Wire реализован через аппаратный мост DS2482S-100, что гарантирует точное соблюдение таймингов протокола без загрузки процессорного ядра.
  • Драйвер SPI (Wiznet W5500): Работает на частоте до 30 МГц с использованием аппаратного DMA-канала. Обеспечивает разгрузку процессора от обработки сетевых пакетов низкого уровня.
  • Драйвер UART 1 (Интерфейс связи с ПО «Аура»): Подключен через высокоскоростной цифровой изолятор (ISO) и трансивер SN75176. Работает в режиме Modbus RTU Slave. Гальваническая изоляция защищает ядро от просадок напряжений на длинных магистралях связи отеля.
  • Драйвер UART 2 (Интерфейс расширения подсистем): Работает в режиме Modbus RTU Master без изоляции. Предназначен для прямого подключения локальных комнатных модулей автоматизации (блоки WirenBoard, кондиционерные шлюзы Daikin).

6. Расширяемое ПО для интеграторов (Функционал PLC / Script Engine)

Для реализации кастомных сценариев автоматизации (конфигурации выключателей, логики работы мастер-клавиш и сценариев «Приветствие/Уход») в ПО заложен изолированный слой выполнения сценариев.

Механизм Script Engine:

  1. Интегратор формирует логику автоматизации в виде стандартного текстового файла конфигурации (формат YAML, аналогично подходу в ESPHome).
  2. Облачное или локальное инженерное ПО компилирует данный файл в промежуточный компактный байт-код — абстрактное синтаксическое дерево (AST).
  3. Байт-код загружается в контроллер по сети через защищенный канал OTA.
  4. Исполняющая виртуальная машина (задача Task_ESPHome_Engine на Core 0) последовательно интерпретирует байт-код.

Политика безопасности Песочницы (Sandbox):

  • Сценариям запрещено вызывать прямые функции чтения/записи указателей памяти (выделение указателей блокируется на этапе компиляции).
  • Сценарии не могут напрямую переключать физические GPIO. Если скрипту нужно включить реле №1, он выполняет запись логической «1» в строго определенный регистр виртуальной карты (Shared Register Map).
  • Задача Task_Peripheral_IO, обнаружив изменение регистра, проверяет его валидность и физически переключает порт через драйвер HAL.

7. Комплексная система обеспечения отказоустойчивости (Fault Tolerance)

Иерархия Watchdog Таймеров:

  • Аппаратный Hardware WDT: Инициализируется на уровне ядра FreeRTOS. Требует регулярного сброса («пинания») от обоих работающих ядер. Если зависает операционная система целиком или ломается аппаратная шина памяти — происходит жесткая перезагрузка контроллера (Hard Reset).
  • Программный Software WDT: Выделенный программный таймер, запущенный внутри доверенного ядра Core 1. Он контролирует время выполнения итерации Script Engine на Core 0. Если пользовательский скрипт попал в бесконечный цикл или вызвал переполнение стека внутри среды выполнения интегратора, программный WDT принудительно убивает и перезапускает изолированную задачу