development

Full Changelog: v0.8...dev

v0.8

New Features

• SPI Bus Selection: Added ethSpiBus configuration to select between SPI2 and SPI3 for Ethernet (when supported by hardware) (#241)
  • New Web UI note component warns users about GPIO conflicts when using Ethernet and PN532 on the same SPI bus
  • Automatic separation of Ethernet and PN532 SPI buses when SPI3 available
• Auth Precompute Cache: Added optional authentication context precomputation for faster HomeKey taps (#224)
  • Enable/disable through the UI (Misc -> HomeKey -> Auth Precompute Cache) or through API via hkAuthPrecomputeEnabled
  • Background task manages cache of precomputed authentication contexts
  • Intelligent cache invalidation when reader data changes
  • Significant performance improvement for repeated taps

Fixes and Improvements

• Logging System: Integrated loggable framework for unified, configurable logging across components
• Memory Safety: Added mutex protection for reader data concurrent access in ReaderDataManager (#224)
• Thread-Safe Snapshots: New getReaderDataCopy() method provides safe reader data snapshots (#224)
• Configuration Validation: Enhanced SPI bus validation and error messages in Web UI (#241)
• Build System: Improved find command compatibility in CMakeLists (#247)
• Stability: Fixed various race conditions and memory safety issues
• HomeKey Issues: Fixed HomeKey authentication issues that prevented Apple Watch and other secondary devices from unlocking the device (fixed #215)
• Web UI Reliability: Enhanced Web UI responsiveness and availability (fixed #237) (fixes? #211)
• Persistence issue: Fixed config deserialization for the neopixel colors (fixed #249)
• Improved OTA: Refactored OTA update process for better stability and cleaner code (#233)

Internal Changes

• Event System Overhaul: Completely refactored event handling from the espp::EventManager to a custom EventBus system for more efficient and flexible event communication (#229)
• Component Updates: Replaced espp/event_manager with esp32-event-bus, this is a simpler implementation that only uses one task and one queue which hugely decreased memory consumption and fixed exhaustion on lower memory models like C3
• New PN532 driver architecture: Migrated from PN532 library to modular pn532_cxx, esp-hal-pn532(Platform HAL) to house platform-agnostic support for future projects and this also motivated me to improve error handling and logging on both the application and transport layer.
• Console Logging: New ConsoleLogSinker provides ANSI colored console output with a cohesive and easily readable format between esp_log logs and loggable logs (used to dispatch logs to mutliple sinks, such as WebSocket to display them on the UI)

Build & CI Improvements

• Nix Flake Update: Updated to nixos-25.11 and switched to mirrexagon/nixpkgs-esp-dev
• LittleFS Handling: Improved LittleFS remounting during OTA updates
• Component Management: Updated to latest library versions

Documentation Updates

• Contributing Guidelines: Added some basic AI/LLM usage guidelines for contributions
• Configuration Guide: Added documentation for new auth cache option and Ethernet SPI bus selection

New Contributors

• @Maxime0506 made their first contribution in #224
• @ionothanus made their first contribution in #241
• @rbouteiller made their first contribution in #247

Full Changelog: v0.7.1...v0.8.0

Happy new Year! 🎉

Release Notes: v0.7.1

Fixes and Code Optimizations

• Stack Size: Increased EventManager subscriber stack from 3072 → 4096 bytes, fixing some stack overflow issues (should fix #213)
• NFC Improvements: Reduced read timeout (500ms → 200ms), adjusted polling delay (50ms → 100ms)
• WebUI: Logs section is now working on a clean build, logs/ was part of the .gitignore and it matches recursively
• HASS: Added HomeKey data to Tag Discovery (Fixes #217) - was left out during the big refactoring in the last release
• HomeKey: Added some fixes in HK-HomeKit-Lib, responses not properly constructed (hopefully can fix the recent apple watch issues)

Updates

Core Dependencies:

• ESP-IDF: v5.5.1 → v5.5.2
• Arduino-ESP32: 3.3.0~1 → 3.3.5
• HomeSpan: release-2.1.3 → release-2.1.6

Build & CI Improvements

• Reorganized CI pipeline: ESP32 builds now depend on the LittleFS job in order to create the merged binary
• New Release Workflow: Automated artifact attachment to GitHub releases
• Firmware Naming: Standardized to {chip}.firmware.bin and {chip}.firmware.factory.bin

Cleanup

• Removed .npmrc and package-lock.json
• Updated to use Bun exclusively for package management
• Updated component dependency hashes

---

Full Changelog: v0.7...v0.7.1

Technical release but some new features too

Important

I messed up the CI configuration and the *.factory.bin does not include the littlefs partition, it will be fixed but for now I’ll put some instructions here for anyone starting fresh.

Make sure to also download the littlefs.bin file alongside the *.factory.bin for your chip and use the command bellow for flashing
esptool.py write_flash 0x0 <*.factory.bin> 0x3e0000 <littlefs.bin>

Been a while, huh? I've been working on this big refactoring as it was an enormous mess and i've done a lot of weird shit in the code that no longer made any sense so it's more of a technical release, though there are some new stuff. Either way, hope you'll all like it 💙.

What's Changed

• Fiy typo by @Noschvie in #191
• Codebase refactored into individual components for separation of responsibilities
• Web interface rebuilt with a modern material design
• Fixes #179
• Fixes #188
• Fixes #198
• Implemented OTA updating through the web interface
• Implemented log viewing on the web interface (closes #162)
• Renamed HomeKey Triggers -> NFC Triggers and HomeKit Triggers -> State Triggers to better represent their purpose
• Added a "Tag Event" trigger in NFC Triggers used for regular NFC Tags, replacing the previous behavior of being treated as "Auth Failed"
• A brand new wiki available at https://rednblkx.github.io/HomeKey-ESP32/
  • This should allow for a more presentable and easier to read wiki along with the help of the search functionality of the wiki
  • Additionally, anyone can now easily contribute to the wiki, relevant files being located here or you can also quickly edit any page while browsing the wiki by pressing the "Edit this page on GitHub" button on the right of any page on the site.
• The naming scheme for the firmware files has been changed and it now follows this format: {chip_model}.firmware(.factory).bin
  • The old merged firmware files now have the suffix "factory" to aid in better understanding their use as this file erases everything

Technical Notes

I've done an extensize refactoring of the codebase that now restructures it into 8 pillars of management to implement a separation of concerns as follows:

• ConfigManager: to handle passing configurations to other components
• HardwareManager: handling hardware actions (Simple GPIO and Pixel)
• LockManager: handling the internal state for the virtual lock that gets synced with HomeKit and Home Assistant
• NfcManager: handling all the NFC communications
• MqttManager: handling MQTT communications
• HomeKitLock: the star of the show, handling all HomeKit-related stuff
• ReaderDataManager: handling the private authentication data for HomeKey
• WebServerManager: handling the Web interface and APIs

The web interface also gets a new look using the Svelte 5 web framework and TailwindCSS + DaisyUI for the styling.

New Contributors

• @Noschvie made their first contribution in #191

Full Changelog: v0.6...v0.7

EDIT
Updated littlefs.bin file attachment, there's a build issue and for some reason the logs route does not load, updated file works

v0.6 - some good additions, some small changes

What's Changed

Features

• PN532 connection recover(#159)
  • It will now attempt to reinitialize the connection if for whatever reason the connection suddenly fails. This is help if there are physical connection issues.
• Added the option for a secondary homekey action(#163)
  • A button can be assigned to trigger an mqtt topic on successful homekey auth instead of the default auth topic if pressedbeforehand.
• Added Ethernet support with custom configuration through the WebUI(#167)
  • Is still necessary to connect to WiFi in order to configure the Ethernet driver
• The hostname is now set to the serial number as seen in the Home App:
  • As it also uses mDNS this makes the device more easily accessible (e.g. HK-12345678.local)
• Moved the "Dumb switch mode" to the Actions section in the HomeKit triggers card
  • The dummy tab is overshadowed by Simple GPIO and they share the settings for the momentary state

Fixes

• The PN532 driver now also works on the ESP32S3 and should no longer get an error

Technical

• PlatformIO is no longer being used and has been replaced with the native ESP-IDF build tools (#165)
• Implemented a configuration provisioning and provider http api that tightly integrates with the WebUI (#164)
• Page fragments are now being cached in session storage to avoid keep requesting the same pages multiple times when you are going through tabs
• Updated ESP-IDF to v5.3.2
• Updated Arduino-ESP32 to v3.1.0
• Updated HomeSpan to v2.1.1

Related PRs

• Add PN532 auto-reconnect functionality by @rednblkx in #159
• Add alternate action on HomeKey success by @rednblkx in #163
• Migrating off PlatformIO by @rednblkx in #165
• Add Ethernet support by @rednblkx in #167

Full Changelog: v0.5...v0.6

v0.5

What's Changed

• Momentary state improvement by @rednblkx in #146
  
• Add NFC tag MQTT ignore option by @rednblkx in #147
  
• Configurable GPIO Pins for the PN532 by @rednblkx in #149
  
• Web Interface reorganization by @rednblkx in #150
• Add Battery reporting from a Smart Lock by @rednblkx in #153
  
• Add HomeKit dumb switch mode by @rednblkx in #154
• Fixed web interface cannot be accessed from Safari
• Fixed HomeKey Triggers Simple GPIO pin assignment
• Other small fixes and adjustments

Note

Release binaries for the ESP32-S3 are no longer included as there are reports of the PN532 not working. However, they can still be downloaded from Github Actions.

Full Changelog: v0.4.1...v0.5

v0.4.1

What's Changed

• Fixed crash on submit for Actions section on the WebUI
• Added Wifi Signal (RSSI) info on the WebUI

Full Changelog: v0.4...v0.4.1

0.4 - Features, fixes and a new look

First of all i just want to thank anyone that showed interest in this thing i made, as of now repository has 455 stars ⭐, a massive increase from the 200ish on the last release which feels absolutely insane for the little project i just made out of spite of Apple, so thank you, it means a lot ♥️.

I've also rewrote part of the wiki, please take a look and let me know what you think.

What's Changed

• Reorganized WebUI and added a splash of color to it
• Added WebUI Authentication (Basic - Digest)
• Added a separate section on the WebUI for triggers, old HomeKey Events and GPIO Actions have been moved here and more properly labeled with a short description
• HomeKit/HomeKey GPIO Trigger (old GPIO Actions) now has an optional momentary state used on a successful HomeKey authentication (#102)
• Added Reboot, Reset HomeKit, Reset WiFi buttons on the WebUI
• Fixed setting timeouts for HomeKey/NFC Triggers (old Events)
• Added field to set the LWT topic on the WebUI(#81)
• Added HomeKey color preview on WebUI(#114)
• Configurable RGB values for the Neopixel
• Payload for the NFC/HK MQTT Topic now includes a "reader_id" field unique per device
• Minor fixes and optimizations
• NFC Tag Detection is now treated as Auth Failure
• Added Pixel Type selector for Neopixel action

Known Issues

• WebUI is not accessible from Safari on macOS Ventura and higher or iOS 18

New Contributors

• @adukale made their first contribution in #114

Full Changelog: v0.3.11...v0.4

Not backwards compatible, if for whatever reason you need to flash the previouse, this won't be possible.

Hotfix

What's Changed

• Fixed Custom States Persistance issue

Full Changelog: v0.3.1...v0.3.11

littlefs.bin only included for posterity, no update to it.

v0.3.1 - Minor Update

What's Changed

• Configurable HomeKey Card Finish (color) from Web UI = Tan, Gold, Silver and Black
• Initialize nfcSuccessPin and nfcFailPin by @gficher in #69
• Implement NeoPixel status LED by @jess-sys in #73
• QoL things and minor fixes

New Contributors

• @gficher made their first contribution in #69
• @jess-sys made their first contribution in #73

Known Issues

• Not saving custom states, if using custom states better stay on previous version

Full Changelog: v0.3...v0.3.1