Skip to content

Terminology

Standard terms used throughout the OpenLatch project. Use these consistently in documentation, use cases, and code comments.

Space Operations

Space Startup

The process of a keyholder arriving and opening the space for use. This includes scanning their NFC card to unlock the door and making the space ready for an event or regular use. A space startup implies that someone is taking responsibility for the space being open.

Space Shutdown

The process of the last person leaving and securing the space. This involves:

  1. Pressing the shutdown button inside the space
  2. A 120-second countdown (configurable via LOCKUP_COUNTDOWN_MS)
  3. ESP32 sends LOCK command to NUKI via BLE
  4. The person exits (mechanical exit is always possible)

Space shutdown is an intentional, deliberate act — the last person takes responsibility for closing the space.

Shutdown Button

The physical button inside the space (GPIO 33) that initiates the space shutdown sequence. Pressing it starts the countdown; pressing it again cancels the shutdown.

Previously referred to as "lock-up button" in some contexts.

Door States

Door Unlock

The NUKI Smart Lock retracts the bolt, allowing the door to be opened. This happens:

  • When a valid NFC card is scanned (access granted)
  • When an organizer approves a conditional access request

Each unlock is temporary — the door auto-relocks after 5 seconds (AUTO_RELOCK_DELAY_MS).

Door Lock

The NUKI Smart Lock engages the bolt. This is the default state and happens:

  • Automatically 5 seconds after each unlock (auto-relock)
  • At the end of a space shutdown sequence
  • When a keyholder explicitly locks the door

Important: A locked door does not mean the space is closed. During an active event, the door is locked between entries (auto-relock) to prevent unauthorized street access. Someone inside can always open the door mechanically for expected visitors.

Door Lock vs. Space Shutdown

Aspect Door Lock Space Shutdown
Frequency Every few minutes (auto-relock) Once per event
Trigger Automatic (timer) or NFC scan Shutdown button press
Intent Secure door between entries Close the space entirely
State after Space is still open/active Space is closed, everyone leaves

Access Concepts

Grace Period

A configurable time window after space shutdown, during which access is still granted. The grace period counts from the shutdown timestamp (grace_ref_time), not from the scheduled slot end time.

Default: 30 minutes (DEFAULT_GRACE_MINUTES in config.h). Configurable per allow-list (header default_grace_minutes) and per entry (grace_minutes field).

Reset on re-entry: If someone scans their card during the grace period and is granted access (GRANTED_GRACE), the grace period resets — a new full grace window starts from that re-entry. This allows "I forgot something" scenarios to chain without expiring.

Example: Event scheduled until 18:00, group stays until 19:30, space shutdown at 19:35. Grace runs until 20:05. Someone re-enters at 20:00 to grab their bag → grace resets, now runs until 20:30.

Fallback: If no shutdown has been recorded (e.g., after ESP32 reboot), the grace period falls back to counting from the slot's scheduled end time.

Allow-List

A signed binary payload containing NFC card UIDs and their access rules. Generated by the backend, signed with Ed25519, cached on the ESP32. The ESP32 uses the allow-list to make offline access decisions.

Access Types

  • UNRESTRICTED: 24/7 access, no time limits. For regular keyholders/members.
  • SCHEDULED: Access only during defined time slots and/or date ranges.
  • EMERGENCY: 24/7 access with mandatory notification. For landlord, fire department.
  • CONDITIONAL: Requires real-time approval from a designated person. For backup keyholders.

Denied Card Escalation

When a known card (UID in the allow-list) is denied access — e.g., outside the scheduled time window — the cardholder can escalate by scanning their card repeatedly. After 3 denied scans within 1 minute, the ESP32 triggers an escalation:

  1. The member calls a guarantor they know (phone number known from community)
  2. The guarantor opens their authenticator app and shares their TOTP code by phone
  3. The member enters the guarantor's key-ID and TOTP code on the CONLAN M1200 keypad: <key_id>#<code>#
  4. The ESP32 verifies the code locally against the guarantor's secret — access granted

The member always initiates contact (there is no intercom at the door). The ESP32 queues escalation events for backend sync; the backend may forward these to a messenger group channel as an additional notification (future feature). This mechanism only works for cards already in the allow-list. TOTP verification is purely local (no network needed). Configurable via ESCALATION_SCAN_COUNT and ESCALATION_SCAN_WINDOW_MS in config.h. See ADR-008 for the TOTP design.

TOTP Keypad Access

An alternative access method using per-user 6-digit one-time codes entered on the CONLAN M1200 keypad. Each user with keypad access has their own TOTP secret, delivered as part of the signed allow-list. Input format: <key_id>#<code>#.

Used for: forgotten NFC card (own code), denied card escalation (guarantor code), conditional access approval (guarantor code), and visitors. The ESP32 verifies codes locally. HOTP backup codes (8 per user, printed list, any-order usage) provide a fallback for users without authenticator apps. See ADR-008.

Roles

Keyholder

A trusted member who can perform space startup and space shutdown. Has an UNRESTRICTED access card.

Member

A person with access to the space, potentially with time-based restrictions.

Guest

A temporary visitor with date-limited or event-limited access (SCHEDULED).

Guarantor

A trusted long-term member (role >= 0x40) who can vouch for another person's entry by sharing their TOTP code over the phone. Guarantors are typically keyholders or experienced regulars. They take responsibility for authorizing one-time access in escalation and conditional access scenarios.

Admin

A board member who manages NFC keys, access rules, and member accounts via the backend. Admins are also guarantors (role 0x80 >= 0x40).

Hardware

NFC Terminal

The outdoor CONLAN M1200 reader (production) or PN532 dev reader. Reads NFC card UIDs and communicates with the ESP32 via Wiegand protocol (production) or I2C (dev).

NUKI Smart Lock Ultra

The battery-powered smart lock on the door, controlled by the ESP32 via BLE. Supports lock, unlock, and unlatch commands.

ESP32 Controller

The microcontroller inside the space that orchestrates everything: reads NFC cards, evaluates access, controls the NUKI lock, provides LED/buzzer feedback, and syncs with the backend.