xecut-me/xecut-lock
1
0
Fork 0
mirror of https://github.com/xecut-me/xecut-lock.git synced 2026-02-11 22:41:18 +00:00
Code Issues Projects Releases Packages Wiki Activity
Smart lock with OTP codes and MQTT support
53 commits 2 branches 0 tags 617 KiB
  • C 86.5%
  • Python 12.8%
  • CMake 0.7%
Find a file
Exact
Valerii Klachkov 3cf73ed7db fix calculate_otp for Decentrala
2026-01-22 20:56:52 +01:00
.vscode publish alive message to mqtt every 10 seconds 2025-10-25 15:20:30 +02:00
main fix calculate_otp for Decentrala 2026-01-22 20:56:52 +01:00
private keep private folder 2025-10-25 17:42:46 +02:00
utils fix year calculation in get_decentrala_otp.py 2026-01-22 20:33:14 +01:00
.clangd experiments with w5500 ethernet 2025-10-20 18:42:35 +02:00
.gitignore keep private folder 2025-10-25 17:42:46 +02:00
CMakeLists.txt experiments with w5500 ethernet 2025-10-20 18:42:35 +02:00
dependencies.lock update esp-idf to v6.0-beta1 2026-01-22 16:46:14 +01:00
README.md add special kdf for Decentrala 2026-01-22 16:45:45 +01:00
sdkconfig update esp-idf to v6.0-beta1 2026-01-22 16:46:14 +01:00

README.md

Xecut Lock

A smart lock project with OTP codes, MQTT control, and WiFi/Ethernet connectivity. Built on the ESP32-S3 microcontroller, but should work on other Espressif microcontrollers as well.

Preparing to Build the Firmware

First, clone the project and then create main/config.h and generate kdf key.

Creating config.h

The main/config.h file specifies WiFi login and password, MQTT credentials, internet connection method selection and lock identifier. This file contains sensitive data and should never be committed.

A config template is located in the main/config.template.h file. Copy it to main/config.h, edit it for your needs, and you can proceed to the next step.

KDF Key Generation

The lock doesn't store OTP keys but generates them on-the-fly for specific users from a KDF key. The key itself is a random set of bytes of arbitrary length.

The key should be located in the private/key.bin directory.

To generate a key, run the script:

./utils/gen_kdf.py ./private/key.bin 48

Where 48 is the key length.

Building the Firmware

To build the project, you'll need ESP-IDF version 6.0 or higher installed and configured. If you don't have this SDK, you can read about installation and toolchain setup here: https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/get-started/index.html.

After that, you can run idf.py build and idf.py flash. No special rituals required.

Connecting the Keypad and Lock

No schematic available yet, pinout is described in the main/hardware.h.

Running and Operation

To generate an OTP key on your computer, use the utils/get_otp.py or utils/get_decentrala_otp.py script:

./utils/get_otp.py ./private/key.bin uid

For example, to generate an OTP key for user with uid 1, the command will look like this:

./utils/get_otp.py ./private/key.bin 1

The script output is a string in otpauth format:

otpauth://totp/1?secret=0000H1111S2222CAAUG6XXKPOBBBBXXXXXI5CQKBP6JXXXX...&issuer=Xecut

Which you can feed to qrencode to get a beautiful QR code that any mobile app for one-time codes will understand:

./utils/get_otp.py ./private/key.bin 1 | qrencode -t UTF8