Doorson Docs

Appearance

Architecture ​

System Diagram ​

┌─────────────┐     ┌─────────────┐
│ md-my-door  │     │md-cloud-    │
│ (mobile app)│     │portal (web) │
└──────┬──────┘     └──────┬──────┘
       │    ┌──────────┐   │
       └────┤ md-npm   ├───┘   (shared Vue components)
            └──────────┘
                 │
          HTTPS / REST
                 │
            ┌────▼────┐
            │md-cloud  │◄──── Keycloak (auth)
            │ (API)    │◄──── PostgreSQL
            └────┬─────┘
                 │
            ┌────▼────┐
            │ md-hub   │◄──── PostgreSQL
            │(MQTT/CAN)│
            └────┬─────┘
                 │
              MQTT
                 │
         ┌───────▼───────┐
         │  md-firmware   │
         │(ESP32-S3 GW)   │
         └───────┬────────┘
                 │
              CAN bus
                 │
    ┌────────────▼────────────┐
    │  Door Controllers       │
    │  + doorson_ble_smartswitch│
    └─────────────────────────┘

Data Flow ​

  1. Door → Cloud: Door controllers send CAN frames → ESP32 gateway translates to MQTT → md-hub processes and stores → md-cloud exposes via REST API
  2. Cloud → Door: User sends command via portal/app → md-cloud → md-hub publishes MQTT → gateway translates to CAN command → door controller executes
  3. Auth: All API requests authenticated via Keycloak OAuth2 tokens. Backend services are resource servers validating JWT tokens.

Backend Services ​

Both md-cloud and md-hub run as Spring Boot 3 applications on JDK 21:

  • Docker images: eclipse-temurin:21-jdk-alpine
  • Database: PostgreSQL with Flyway-managed migrations
  • Scheduling: ShedLock for distributed task locking
  • Logging: Log4j2

md-cloud ​

Core API service. Handles door management, scheduling, holidays, user provisioning. Integrates with Keycloak admin API for user management.

  • Debug port: 9110
  • Dev setup requires AUTH_HOST=doorson-auth in /etc/hosts

md-hub ​

Processes CAN controller data packets arriving via MQTT. Manages door controller settings and phone numbers.

  • Debug port: 9111
  • Uses Eclipse Paho MQTT v5 client + Spring Integration

Frontend Apps ​

Both md-cloud-portal and md-my-door are built with Vue 3 + Quasar 2 + Vite:

  • Auth: Keycloak JS adapter
  • State: Pinia stores
  • Shared code: md-npm package (consumed as local .tgz)
  • md-my-door additionally uses Cordova for native Android/iOS builds

Firmware ​

md-firmware (Gateway) ​

ESP-IDF v5.5.2 targeting ESP32-S3. Bridges CAN bus (TWAI) to cloud via MQTT. Features:

  • BLE WiFi provisioning (NimBLE)
  • OTA firmware updates
  • HTTP config server with basic auth
  • LED status indicators + button hold actions
  • CI/CD: GitHub Actions builds on tag push (v*.* or v*.*-rc*)

doorson_ble_smartswitch ​

nRF Connect SDK (Zephyr) targeting nRF52840. BLE peripheral with Acconeer A121 radar for presence detection.

  • Advertises as "Doorson SmartSwitch" over BLE
  • Flash via J-Link SWD or UART DFU