Access Engine Memory Safety & Stability

The QRTick Access Engine is designed to run reliably on extreme edge hardware, such as the Raspberry Pi Zero 2W or other edge controllers with limited memory (e.g., 512MB of RAM).

To ensure the gate remains fast, responsive, and completely crash-proof over months of continuous operation, we have implemented several critical "memory safety" mechanisms. This document outlines these measures in plain English.

1. The USB Polling Fix (Stopping the `pcscd` Leak)

The Problem: The background program that talks to the physical NFC scanner (called pcscd) has a known flaw. If you ask it "is there a card reader plugged in?" too rapidly, it slowly hoards tiny amounts of memory until the system crashes. Previously, our system was asking this question 3 times every second, resulting in a massive 150MB memory leak over a 12-hour period. The Solution: We updated the engine to "cache" its connection to the reader, only asking the USB port for a fresh hardware check once every 5 seconds. This 16x reduction in traffic completely stopped the memory leak, giving the gate an extra ~150MB of breathing room.

2. Realtime Event Debouncing (Preventing Bulk-Update Crashes)

The Problem: The gate maintains a live, always-on connection to the cloud database. If a staff member bulk-updated 50 members at once on the dashboard, the cloud would instantly fire 50 "update" alerts to the gate. Previously, the gate would try to download and parse 50 massive gym rosters simultaneously, instantly maxing out the RAM and crashing the controller. The Solution: We implemented a "debounce" mechanism. Now, if 50 updates arrive at the same time, the gate simply sets a single flag saying "I need to update." It waits for the barrage of alerts to finish, and then calmly performs one sequential download. This makes bulk updates 100% safe.

3. The 12-Hour Watchdog Restarts

The Problem: Even with perfect code, physical hardware running 24/7 in a gym environment can encounter unpreventable glitches—a dropped WiFi packet leaving a socket open, or the physical USB bus to the scanner locking up due to static electricity. The Solution: We installed an automated "Watchdog" that forcefully restarts the USB daemon and the Access Engine twice a day (at exactly 3:00 AM and 3:00 PM). This takes less than 5 seconds and is invisible to users. It acts as a guaranteed self-healing mechanism, returning all memory to the system and establishing fresh connections to the cloud and the scanner.

4. Operating System Hardening

During deployment, the installation script automatically strips the controller down to the bare minimum required to operate the gate:

GPU Memory Split: We reduce the memory allocated to graphics (which we don't use) down to the absolute minimum (16MB), giving that RAM back to the main processor.
Hardware Pruning: We permanently disable the edge device's Bluetooth and Audio chips, saving power and background memory.
ZRAM Compression: We install a specialized "RAM Disk" that automatically compresses memory in real-time, effectively allowing the edge device to squeeze 1.5x more data into its 512MB limit before slowing down.

Summary