Nuki Hub turns an ESP32 into a local bridge for Nuki locks

A BLE client on one side, an MQTT broker on the other

The mechanism is a translation, and the two protocols sit on opposite sides of it. The firmware runs on an ESP32 module, talks to a Nuki Lock and or Opener over Bluetooth Low Energy, and uses MQTT to integrate with other systems. On the MQTT side it exposes the lock state and more, and it accepts commands, so locking, unlocking and changing the Nuki Lock or Opener configuration all arrive as MQTT messages. The stated scope is an efficient way to integrate Nuki devices in a local home automation platform, and the topics named in the repository metadata, mqtt, home-assistant, home-automation, fhem and iobroker, point at the ecosystems this is aimed at. The consequence of the MQTT design is that the hub is not a cloud client with a local fallback. It is a local device that happens to speak a protocol home automation platforms already understand.

It deliberately does not register with the Nuki mobile app

This is the constraint that decides who should use the project, and the README states it in bold. Nuki Hub does not integrate with the Nuki mobile app and cannot register itself as a bridge in the official Nuki mobile app. That is a deliberate architectural position, not a missing feature. The official Nuki Bridge does the opposite, registering with the app so it can be reached from anywhere through the vendor's cloud. If your requirement is remote access through the Nuki app on a phone outside your home network, Nuki Hub is the wrong project. If the requirement is that your home automation platform can see the lock state and act on it locally, then the MQTT route is the point. The comparison table in the README makes the split explicit, listing MQTT, wired LAN support with optional Power over Ethernet, control via GPIO, and a hybrid mode for WiFi and Thread connected locks as Nuki Hub features that the Nuki Bridge does not have, while cloud support in Nuki Hub is described as optional through a smarthome solution.

The BLE controller is the reason the original ESP32 is not recommended

The hardware guidance is unusually blunt for a firmware project, and it comes down to one component. The README does not recommend the original ESP32 or the ESP32-Solo1 because those devices experience unexpected crashes related to the closed-source BLE controller, and in newer models such as the ESP32-S3, ESP32-P4, ESP32-C3, ESP32-C5, ESP32-C6, ESP32-C61 and ESP32-H2 those crashes are seen a lot less. A crash in the BLE controller takes the whole hub down, because the hub is the BLE client, so this is not a cosmetic issue. The advice for buying new hardware is the ESP32-P4 or the ESP32-S3 with PSRAM, looking for an ESP32-S3 with the designation N>=4 and R>=2, such as an ESP32-S3 N16R8. The recommended list is ranked best to worst, with the ESP32-P4 and ESP32-C5 module first but marked untested, and the not-recommended list runs from the ESP32 with PSRAM down to the ESP32-H2.

Dual core matters because the hub runs four jobs at once

Nuki Hub uses both CPU cores where they are available, and the reason given is the workload: the HTTP server, the MQTT client, the BLE scanner and the BLE client are all tasks that need processing. On a single core device these compete, and the README says the result is that it runs better on dual-core parts. That single sentence explains most of the hardware ranking. The ESP32-P4 with an ESP32-C6 or ESP32-C5 module is described as the most powerful option, with the highest CPU clocks, the largest flash and PSRAM, Ethernet, PoE and WiFi6, and 5 GHz WiFi when the C5 acts as a co-processor. The ESP32-S3 is a dual-core part with many GPIO pins, the ability to add PSRAM, the ability to attach Ethernet modules over SPI, and optional PoE powering. What the S3 gives up against the P4 is the ability to use some Ethernet modules that only the original ESP32 and the P4 support, and WiFi6. The ESP32-C5 adds higher clocks than the C6 plus PSRAM and 5 GHz WiFi6, and the C61 adds PSRAM to the C6.

Wired Ethernet is a real option, and it needs PoE hardware

The list of supported modules with built-in wired Ethernet is long, and it names specific products rather than generic parts: the Olimex ESP32-POE and ESP32-POE-ISO, the WT32-ETH01, the M5Stack Atom POE and the M5Stack PoESP32 Unit, four LilyGO T-ETH variants including the ESP32S3 and ELite, the GL-S10 in revisions 2.1 and 2.3, and several Waveshare boards including the ESP32-S3-ETH, the ESP32-S3-POE-ETH, the ESP32-P4-NANO and the ESP32-P4-Module-DEV-KIT, plus the Espressif ESP32-P4-Function-EV-Board. The README notes that in principle any ESP32 with a built-in Ethernet port is supported, but that it might require additional setup using the Custom LAN setup option, and points at a section titled Connecting via Ethernet for the details. For a hub in a cupboard, PoE removes the power supply question, and a native Ethernet port removes the Wi-Fi reliability question in the same box.

The build system is PlatformIO driven, with a Makefile on top

The repository is built with PlatformIO and wrapped in a Makefile, and the Makefile is the more useful entry point because it enumerates the boards for you. It reads platformio.ini and extracts the environment names with a grep expression, splitting them into regular boards, debug boards whose names end in _dbg, and updater boards whose names are prefixed with updater_. The default target builds esp32 in release mode, release builds every board, updater builds the updater variant of each, debug builds the debug variants, and all does the three together. The underlying build is a single command, pio run with the environment flag, and the updater variant runs the same command against the updater directory. The help target prints the available targets and the board list, which is the fastest way to find the exact environment name for the module you own.

Building one target, and cleaning the workspace afterwards

Because the board list is derived from platformio.ini rather than hard-coded, you build a specific module by name. The make help output shows the three documented entry points, and the individual board targets are generated from the environment list:

	@echo "  make                  - Default build (ESP32 in release mode)"
	@echo "  make deps             - Install software dependencies (PlatformIO)"
	@echo "  make all              - Build all boards in both release and debug modes"

Cleaning is a single target, and it removes the release and debug directories, the PlatformIO build output, the dependency lock files and the managed components for both the main tree and the updater tree. That list matters when a build goes wrong after a dependency change, since the lock files and managed components are exactly what a stale build would reuse. A separate deps target installs the software dependencies, which the help output describes as the PlatformIO install step. The updater directory has its own dependency and component directories, so a failed updater build is not fixed by cleaning only the main tree.

Editorial conclusion

Nuki Hub suits someone who already owns a Nuki lock, wants the lock reachable from Home Assistant, FHEM or ioBroker over MQTT, and prefers to keep the device on the local network rather than talking to a vendor cloud. It does not suit someone who wants the Nuki mobile app to see the hub, because the README states plainly that Nuki Hub does not integrate with the app and cannot register as a bridge in it. Before buying hardware, check that your module has BLE, since the ESP32-S2 cannot run it at all, prefer an ESP32-S3 with PSRAM such as a N16R8, and note that the last push to the repository was on 2026-10-20 with release 9.17 dated 2026-09-05.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. technyon/nuki_hub on GitHub