# technyon/nuki_hub architecture

> Architecture diagram of the GitHub repository technyon/nuki_hub, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/technyon/nuki_hub
- Repository: https://github.com/technyon/nuki_hub

## Overview

Nuki Hub is ESP32 firmware that bridges Nuki locks, openers, and keypads to local home-automation systems. Its principal workflow is to initialize network and device services, communicate with Nuki devices over BLE, then expose state and accept commands through MQTT; users can also configure the hub through its web interface and GPIO. The graph preserves documented capabilities such as Ethernet, Home Assistant discovery, and import/export. Source excerpts are partial, so some subsystem links are based on README statements rather than inspected call sites.

Main entry points: [`src/main.cpp`](https://github.com/technyon/nuki_hub/blob/master/src/main.cpp) (Hub runtime), [`src/WebCfgServer.h`](https://github.com/technyon/nuki_hub/blob/master/src/WebCfgServer.h) (Web configuration), [`src/NukiNetwork.cpp`](https://github.com/technyon/nuki_hub/blob/master/src/NukiNetwork.cpp) (Network manager), [`lib/BleScanner/src/BleScanner.cpp`](https://github.com/technyon/nuki_hub/blob/master/lib/BleScanner/src/BleScanner.cpp) (BLE scanning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Firmware runtime"]
  node_firmware["Hub runtime<br/>[main.cpp]"]
  node_config["Preferences<br/>[PreferencesKeys.h]"]
  node_logger["Logging<br/>[Logger.h]"]
  node_millis["Timing utility<br/>[EspMillis.h]"]
  node_restart["Restart reasons<br/>[RestartReason.h]"]
end

subgraph group_device["Nuki devices"]
  node_ble["BLE scanning<br/>[BleScanner.cpp]"]
  node_nuki_lock["Lock protocol"]
  node_nuki_opener["Opener protocol"]
  node_nuki_wrapper["Device wrapper<br/>[NukiWrapper.h]"]
  node_opener_wrapper["Opener wrapper"]
end

subgraph group_connectivity["Network connectivity"]
  node_network["Network manager<br/>[NukiNetwork.cpp]"]
  node_wifi["Wi-Fi device<br/>[WifiDevice.cpp]"]
  node_ethernet["Ethernet device<br/>[EthernetDevice.cpp]"]
end

subgraph group_integration["Home automation"]
  node_mqtt_client["MQTT client<br/>[MqttClient.cpp]"]
  node_mqtt_transport["MQTT transport<br/>[Transport.h]"]
  node_mqtt_topics["MQTT topics<br/>[MqttTopics.h]"]
  node_mqtt_receiver["Command receiver<br/>[MqttReceiver.h]"]
  node_publisher["State publisher<br/>[NukiPublisher.cpp]"]
  node_discovery["HA discovery"]
  node_mqtt_logging["MQTT logging<br/>[Logging.h]"]
end

subgraph group_management["Configuration and control"]
  node_gpio["GPIO control<br/>[Gpio.h]"]
  node_web_config["Web configuration<br/>[WebCfgServer.h]"]
  node_http_server["HTTP server"]
  node_import_export["Import and export<br/>[ImportExport.cpp]"]
  node_duo_auth["Duo authentication<br/>[DuoAuthLib.cpp]"]
  node_http_core["HTTP core<br/>[PsychicCore.h]"]
  node_http_request["HTTP requests<br/>[PsychicRequest.h]"]
end

node_user(("Home automation user"))
node_device_actor(("Nuki device"))
node_ha(("Home automation"))
node_mqtt_broker(("MQTT broker"))

node_user -->|"configures"| node_firmware
node_firmware -->|"initializes"| node_network
node_firmware -->|"starts device"| node_nuki_wrapper
node_firmware -->|"starts lock"| node_nuki_lock
node_firmware -->|"starts opener"| node_opener_wrapper
node_firmware -->|"configures"| node_gpio
node_firmware -->|"starts server"| node_web_config
node_firmware -->|"uses"| node_import_export
node_firmware -->|"uses"| node_config
node_firmware -->|"uses"| node_restart
node_firmware -.->|"discovers devices"| node_ble
node_device_actor -->|"advertises"| node_ble
node_ble -->|"communicates over BLE"| node_nuki_lock
node_ble -->|"communicates over BLE"| node_nuki_opener
node_nuki_wrapper -.->|"controls"| node_nuki_lock
node_opener_wrapper -.->|"controls"| node_nuki_opener
node_network -.->|"selects interface"| node_wifi
node_network -.->|"selects interface"| node_ethernet
node_firmware -.->|"integrates MQTT"| node_mqtt_client
node_mqtt_client -->|"uses transport"| node_mqtt_transport
node_mqtt_client -->|"publishes and subscribes"| node_mqtt_broker
node_mqtt_receiver -.->|"uses topics"| node_mqtt_topics
node_publisher -.->|"uses topics"| node_mqtt_topics
node_mqtt_receiver -->|"accepts commands"| node_nuki_lock
node_mqtt_receiver -->|"accepts commands"| node_nuki_opener
node_publisher -->|"publishes state"| node_mqtt_broker
node_ha -->|"exchanges messages"| node_mqtt_broker
node_discovery -->|"announces devices"| node_ha
node_user -->|"configures"| node_web_config
node_web_config -->|"serves through"| node_http_server
node_http_server -.->|"uses"| node_http_core
node_http_request -->|"uses"| node_http_core
node_firmware -->|"uses"| node_logger
node_logger -->|"uses"| node_mqtt_logging
node_firmware -->|"uses"| node_millis
node_web_config -.->|"supports configuration transfer"| node_import_export
node_web_config -.->|"optional authentication"| node_duo_auth
node_network -.->|"provides connectivity"| node_mqtt_client

click node_firmware "https://github.com/technyon/nuki_hub/blob/master/src/main.cpp"
click node_config "https://github.com/technyon/nuki_hub/blob/master/src/PreferencesKeys.h"
click node_logger "https://github.com/technyon/nuki_hub/blob/master/src/Logger.h"
click node_ble "https://github.com/technyon/nuki_hub/blob/master/lib/BleScanner/src/BleScanner.cpp"
click node_nuki_lock "https://github.com/technyon/nuki_hub/blob/master/src/NukiNetworkLock.cpp"
click node_nuki_opener "https://github.com/technyon/nuki_hub/blob/master/src/NukiNetworkOpener.cpp"
click node_nuki_wrapper "https://github.com/technyon/nuki_hub/blob/master/src/NukiWrapper.h"
click node_opener_wrapper "https://github.com/technyon/nuki_hub/blob/master/src/NukiOpenerWrapper.h"
click node_network "https://github.com/technyon/nuki_hub/blob/master/src/NukiNetwork.cpp"
click node_wifi "https://github.com/technyon/nuki_hub/blob/master/src/networkDevices/WifiDevice.cpp"
click node_ethernet "https://github.com/technyon/nuki_hub/blob/master/src/networkDevices/EthernetDevice.cpp"
click node_mqtt_client "https://github.com/technyon/nuki_hub/blob/master/lib/espMqttClient/src/MqttClient.cpp"
click node_mqtt_transport "https://github.com/technyon/nuki_hub/blob/master/lib/espMqttClient/src/Transport/Transport.h"
click node_mqtt_topics "https://github.com/technyon/nuki_hub/blob/master/src/MqttTopics.h"
click node_mqtt_receiver "https://github.com/technyon/nuki_hub/blob/master/src/MqttReceiver.h"
click node_publisher "https://github.com/technyon/nuki_hub/blob/master/src/NukiPublisher.cpp"
click node_discovery "https://github.com/technyon/nuki_hub/blob/master/src/HomeAssistantDiscovery.cpp"
click node_gpio "https://github.com/technyon/nuki_hub/blob/master/src/Gpio.h"
click node_web_config "https://github.com/technyon/nuki_hub/blob/master/src/WebCfgServer.h"
click node_http_server "https://github.com/technyon/nuki_hub/blob/master/lib/PsychicHttp/src/PsychicHttpServer.h"
click node_import_export "https://github.com/technyon/nuki_hub/blob/master/src/ImportExport.cpp"
click node_duo_auth "https://github.com/technyon/nuki_hub/blob/master/lib/DuoAuthLibrary/src/DuoAuthLib.cpp"
click node_millis "https://github.com/technyon/nuki_hub/blob/master/src/EspMillis.h"
click node_restart "https://github.com/technyon/nuki_hub/blob/master/src/RestartReason.h"
click node_mqtt_logging "https://github.com/technyon/nuki_hub/blob/master/lib/espMqttClient/src/Logging.h"
click node_http_core "https://github.com/technyon/nuki_hub/blob/master/lib/PsychicHttp/src/PsychicCore.h"
click node_http_request "https://github.com/technyon/nuki_hub/blob/master/lib/PsychicHttp/src/PsychicRequest.h"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_firmware,node_config,node_logger,node_millis,node_restart,node_user toneBlue
class node_ble,node_nuki_lock,node_nuki_opener,node_nuki_wrapper,node_opener_wrapper toneAmber
class node_network,node_wifi,node_ethernet toneMint
class node_mqtt_client,node_mqtt_transport,node_mqtt_topics,node_mqtt_receiver,node_publisher,node_discovery,node_mqtt_logging toneRose
class node_gpio,node_web_config,node_http_server,node_import_export,node_duo_auth,node_http_core,node_http_request,node_device_actor,node_ha,node_mqtt_broker toneIndigo
```

## Components

### Firmware runtime

- [Hub runtime](https://github.com/technyon/nuki_hub/blob/master/src/main.cpp): `src/main.cpp`
- [Preferences](https://github.com/technyon/nuki_hub/blob/master/src/PreferencesKeys.h): `src/PreferencesKeys.h`
- [Logging](https://github.com/technyon/nuki_hub/blob/master/src/Logger.h): `src/Logger.h`
- [Timing utility](https://github.com/technyon/nuki_hub/blob/master/src/EspMillis.h): `src/EspMillis.h`
- [Restart reasons](https://github.com/technyon/nuki_hub/blob/master/src/RestartReason.h): `src/RestartReason.h`

### Nuki devices

- [BLE scanning](https://github.com/technyon/nuki_hub/blob/master/lib/BleScanner/src/BleScanner.cpp): `lib/BleScanner/src/BleScanner.cpp`
- [Lock protocol](https://github.com/technyon/nuki_hub/blob/master/src/NukiNetworkLock.cpp): `src/NukiNetworkLock.cpp`
- [Opener protocol](https://github.com/technyon/nuki_hub/blob/master/src/NukiNetworkOpener.cpp): `src/NukiNetworkOpener.cpp`
- [Device wrapper](https://github.com/technyon/nuki_hub/blob/master/src/NukiWrapper.h): `src/NukiWrapper.h`
- [Opener wrapper](https://github.com/technyon/nuki_hub/blob/master/src/NukiOpenerWrapper.h): `src/NukiOpenerWrapper.h`

### Network connectivity

- [Network manager](https://github.com/technyon/nuki_hub/blob/master/src/NukiNetwork.cpp): `src/NukiNetwork.cpp`
- [Wi-Fi device](https://github.com/technyon/nuki_hub/blob/master/src/networkDevices/WifiDevice.cpp): `src/networkDevices/WifiDevice.cpp`
- [Ethernet device](https://github.com/technyon/nuki_hub/blob/master/src/networkDevices/EthernetDevice.cpp): `src/networkDevices/EthernetDevice.cpp`

### Home automation

- [MQTT client](https://github.com/technyon/nuki_hub/blob/master/lib/espMqttClient/src/MqttClient.cpp): `lib/espMqttClient/src/MqttClient.cpp`
- [MQTT transport](https://github.com/technyon/nuki_hub/blob/master/lib/espMqttClient/src/Transport/Transport.h): `lib/espMqttClient/src/Transport/Transport.h`
- [MQTT topics](https://github.com/technyon/nuki_hub/blob/master/src/MqttTopics.h): `src/MqttTopics.h`
- [Command receiver](https://github.com/technyon/nuki_hub/blob/master/src/MqttReceiver.h): `src/MqttReceiver.h`
- [State publisher](https://github.com/technyon/nuki_hub/blob/master/src/NukiPublisher.cpp): `src/NukiPublisher.cpp`
- [HA discovery](https://github.com/technyon/nuki_hub/blob/master/src/HomeAssistantDiscovery.cpp): `src/HomeAssistantDiscovery.cpp`
- [MQTT logging](https://github.com/technyon/nuki_hub/blob/master/lib/espMqttClient/src/Logging.h): `lib/espMqttClient/src/Logging.h`

### Configuration and control

- [GPIO control](https://github.com/technyon/nuki_hub/blob/master/src/Gpio.h): `src/Gpio.h`
- [Web configuration](https://github.com/technyon/nuki_hub/blob/master/src/WebCfgServer.h): `src/WebCfgServer.h`
- [HTTP server](https://github.com/technyon/nuki_hub/blob/master/lib/PsychicHttp/src/PsychicHttpServer.h): `lib/PsychicHttp/src/PsychicHttpServer.h`
- [Import and export](https://github.com/technyon/nuki_hub/blob/master/src/ImportExport.cpp): `src/ImportExport.cpp`
- [Duo authentication](https://github.com/technyon/nuki_hub/blob/master/lib/DuoAuthLibrary/src/DuoAuthLib.cpp): `lib/DuoAuthLibrary/src/DuoAuthLib.cpp`
- [HTTP core](https://github.com/technyon/nuki_hub/blob/master/lib/PsychicHttp/src/PsychicCore.h): `lib/PsychicHttp/src/PsychicCore.h`
- [HTTP requests](https://github.com/technyon/nuki_hub/blob/master/lib/PsychicHttp/src/PsychicRequest.h): `lib/PsychicHttp/src/PsychicRequest.h`

### Other components

- **Home automation user**
- **Nuki device**
- **Home automation**
- **MQTT broker**

## Connections

- Home automation user → Hub runtime: configures
- Hub runtime → Network manager: initializes (evidence: `src/main.cpp`)
- Hub runtime → Device wrapper: starts device (evidence: `src/main.cpp`)
- Hub runtime → Lock protocol: starts lock (evidence: `src/main.cpp`)
- Hub runtime → Opener wrapper: starts opener (evidence: `src/main.cpp`)
- Hub runtime → GPIO control: configures (evidence: `src/main.cpp`)
- Hub runtime → Web configuration: starts server (evidence: `src/main.cpp`)
- Hub runtime → Import and export: uses (evidence: `src/main.cpp`)
- Hub runtime → Preferences: uses (evidence: `src/main.cpp`)
- Hub runtime → Restart reasons: uses (evidence: `src/main.cpp`)
- Hub runtime → BLE scanning: discovers devices
- Nuki device → BLE scanning: advertises
- BLE scanning → Lock protocol: communicates over BLE
- BLE scanning → Opener protocol: communicates over BLE
- Device wrapper → Lock protocol: controls
- Opener wrapper → Opener protocol: controls
- Network manager → Wi-Fi device: selects interface
- Network manager → Ethernet device: selects interface
- Hub runtime → MQTT client: integrates MQTT
- MQTT client → MQTT transport: uses transport
- MQTT client → MQTT broker: publishes and subscribes
- Command receiver → MQTT topics: uses topics
- State publisher → MQTT topics: uses topics
- Command receiver → Lock protocol: accepts commands
- Command receiver → Opener protocol: accepts commands
- State publisher → MQTT broker: publishes state
- Home automation → MQTT broker: exchanges messages
- HA discovery → Home automation: announces devices
- Home automation user → Web configuration: configures
- Web configuration → HTTP server: serves through
- HTTP server → HTTP core: uses
- HTTP requests → HTTP core: uses (evidence: `lib/PsychicHttp/src/PsychicHandler.h`)
- Hub runtime → Logging: uses (evidence: `src/main.cpp`)
- Logging → MQTT logging: uses (evidence: `src/Logger.h`)
- Hub runtime → Timing utility: uses (evidence: `src/main.cpp`)
- Web configuration → Import and export: supports configuration transfer
- Web configuration → Duo authentication: optional authentication
- Network manager → MQTT client: provides connectivity
