Skip to content

UC-001: Regular Member Access

Actor: Member Priority: Must Status: Implemented (protocol + firmware allow-list evaluation)

Summary

A regular hackerspace member unlocks the door at any time using their personal NFC card.

Preconditions

  • Member has an active membership
  • Member has been issued a DESFire EV2/EV3 NFC card
  • Card UID is registered in the backend and included in the allow-list
  • ESP32 has a valid, signed allow-list containing the member's entry

Main Flow

  1. Member holds NFC card against the outdoor terminal
  2. Terminal reads the card UID (with DESFire authentication in production)
  3. ESP32 receives the UID from the card reader
  4. ESP32 looks up the UID in the cached allow-list
  5. Entry has access type UNRESTRICTED — access granted
  6. ESP32 sends unlock command to NUKI Smart Lock via BLE
  7. Green LED lights up, buzzer gives short confirmation beep
  8. Door unlocks for 5 seconds, then auto-relocks

Alternative Flows

A1: Member initiates space shutdown

  1. Member is the last person leaving and presses the shutdown button inside (see UC-008)
  2. 120-second countdown starts, then NUKI locks the door
  3. Shutdown event logged

Note: The door also locks automatically 5 seconds after each unlock (auto-relock). This is normal operation and does not mean the space is closed.

A2: Stale allow-list

  1. At step 4, the allow-list has expired (valid_until passed, no recent sync)
  2. Since entry is UNRESTRICTED, access is still granted (permanent keyholders are trusted even with stale data)

Error Flows

E1: Card not in allow-list

  1. At step 4, UID is not found
  2. Red LED, denial buzzer pattern
  3. Access denied, event logged for next sync

E2: NUKI unreachable

  1. At step 6, BLE connection to NUKI fails
  2. Red LED flashes, error buzzer
  3. ESP32 retries BLE connection (up to 3 attempts)
  4. If still failing, access denied with error feedback

Postconditions

  • Door is unlocked for 5 seconds
  • Access event is queued for reporting at next backend sync

Access Rule

  • Access type: UNRESTRICTED
  • Time slots: None (24/7)
  • Notifications: None (default)
  • Grace period: N/A

Notes

  • This is the most common use case, expected to cover ~80% of all door interactions.
  • Members can always initiate space shutdown, regardless of any time restrictions.
  • Scanning a card is a "space startup" — the keyholder takes responsibility for the space being open.