Skip to content

ADR-000: Universal Open Source Project

Status: Accepted Date: 2026-03-17

Context

OpenLatch was originally built for a specific hackerspace in Berlin. However, the problem it solves — secure, offline-capable, cryptographically verified NFC access control — is common to many types of community spaces:

  • Hackerspaces and makerspaces
  • Coworking spaces
  • Community centres and shared workshops
  • Volunteer-run clubs and associations
  • Any space that needs member access control without a commercial subscription

Each location has different hardware, different access rules, and different operational constraints. A coworking space may need scheduled access with strict time slots. A hackerspace may prefer unrestricted 24/7 access for members. One site uses wired Ethernet; another relies on WiFi. One has a physical door solenoid; another has only a NUKI Smart Lock.

A single rigid implementation cannot serve all of these. At the same time, the security- critical core — Ed25519 signature verification, allow-list evaluation, BLE lock control — must be shared and battle-tested, not duplicated across forks.

Decision

OpenLatch is a universal reference implementation

The project is designed to be cloned, configured, and deployed by any community space. It is not "the Berlin hackerspace door system" that others adapt — it is the upstream that the Berlin installation is one instance of. All location-specific choices are expressed as configuration, not as code changes.

Compile-time feature flags control hardware and behaviour

Site-specific configuration is done through build flags in platformio.ini, overridden locally via firmware/local.ini (git-ignored). No source file should need to be edited to deploy OpenLatch at a new location.

Flag Controls
USE_ETHERNET Wired Ethernet as primary network interface (production)
USE_WIFI_FALLBACK WiFi as standby if Ethernet link drops
USE_PN532 PN532 I2C reader instead of Wiegand (development/prototyping)
USE_WIEGAND CONLAN M1200 Wiegand reader (production, default)
USE_DOOR_HARDWARE Solenoid, sensors, SX1509 control panel (physical door installations)
CORE_DEBUG_LEVEL Verbosity of serial debug output

New hardware variants and optional features should follow this pattern: off by default, enabled by a flag, guarded by #ifdef in firmware, documented in firmware/local.ini.example.

Runtime configuration lives in NVS

Values that differ between deployed devices of the same type (device token, backend URL, WiFi credentials, master public key) are stored in ESP32 NVS (Non-Volatile Storage) and loaded at boot. They are provisioned per-device, not compiled in.

The security core is not configurable

The Ed25519 signature chain, the OL02 binary protocol, the TOTP/HOTP implementation, and the access evaluation logic are fixed. They are not feature-flagged and not site-specific. A location that wants different security behaviour should open an issue or submit a pull request rather than patching locally — weakening the security model in one installation weakens the reference that others rely on.

Contributions are welcome

OpenLatch is open source. If your installation needs a feature that is not yet supported:

  1. Open an issue to discuss the requirement before building. Others may have the same need, or there may be an existing approach you are not aware of.
  2. Submit a pull request with the implementation. New hardware support, additional access types, monitoring integrations, and admin UI improvements are all in scope.
  3. Use feature flags for new optional hardware or behaviour so existing deployments are unaffected by default.
  4. Keep the security core intact. Changes to signature verification, the binary protocol, or access evaluation logic require broader discussion and review.

Bug reports, hardware compatibility reports, and documentation improvements are equally valued contributions.

Consequences

  • Any community space can deploy OpenLatch without forking the repository
  • Location-specific settings are isolated to firmware/local.ini (git-ignored) and NVS — git pull for upstream updates never clobbers local configuration
  • New hardware support is additive and opt-in — existing deployments are not affected
  • The security-critical core is shared across all installations and reviewed collectively
  • All ADRs in this project document decisions that apply to the universal implementation; location-specific trade-offs belong in local documentation, not here

See also