Project
| # | Title | Team Members | TA | Documents | Sponsor |
|---|---|---|---|---|---|
| 17 | NFC Selector and Running-State Indicator for Concurrent AI Runtimes |
Achintya Mohan Kevin Wiszowaty Tommy Zeng |
Shiyuan Duan | ||
| # NFC Selector and Running-State Indicator for Concurrent AI Runtimes Team Members: - Ziyan Zeng (ziyanz6) - Kevin Wiszowaty (kevinjw4) - Achintya Mohan (mohan19) # Problem When multiple concurrent AI coding-agent runtimes are running for different projects, it is difficult to determine which runtimes are active, which projects are waiting for input, and which tasks have produced new feedback. Screen-based project-management tools and software notifications are easy to miss when several projects progress simultaneously. We want to create a physical interface that limits the active working set to a manageable number of projects and provides an immediately visible indication of which projects are running or require attention. The system will complement an existing project-management system rather than replace it. # Solution We will design and build a vertical electromechanical device with three fully functional card slots and an architecture that can scale to six slots. Each NFC card represents one project. Its writable NDEF record contains a project ID, display label, path metadata, and revision information. The card UID is treated as its immutable hardware identity and is associated with a project by a host-side authorization system. The device supports NFC reading and writing. An authorized operator can initialize a blank card, assign it to a project, and write its project record. An existing card can be overwritten only after the host displays the old record and receives explicit operator confirmation. Every write is followed by read-back verification. At the beginning of a work session, the user inserts up to three authorized cards and presses each selected card down once. While the associated runtime is operating normally, the card remains lowered. When the runtime finishes, becomes blocked, or requires input, the host control hub commands the corresponding actuator to raise the card. RGB LEDs, an OLED display, and a buzzer provide additional feedback. After the user acknowledges the event through the host computer, the card is lowered again. Removing a card releases its project from the active working set. The host-side control hub bridges the physical device, local project-management software, and concurrent runtimes. A runtime adapter will connect to Codex pre-run and post-run hooks for the final demonstration. A simulator will generate deterministic events for hardware and regression testing. The control hub will also synchronize versioned NFC system state with a private GitHub repository. GitHub provides cloud backup, version history, and audit information, but it is not required for real-time mechanical control. If the network is unavailable, the local system continues to operate and queues changes for later synchronization. # Solution Components ## NFC Reader and Card Memory Subsystem This subsystem identifies cards and supports card initialization, metadata updates, and write verification. Planned components: - ST25R3916B NFC reader IC: one per slot, three total in the final prototype. - 13.56 MHz antenna and matching/tuning network: one per slot. - NTAG213 or NTAG215 NFC cards: at least three. - PN532 reader modules for early NFC read/write bring-up. The final PCB will use independent reader channels and physically separated antennas to reduce cross-reading between adjacent slots. The PN532 implementation is only an early validation path; the final design uses the custom ST25R3916B-based reader channels. ## NFC Data Format and Provisioning The user memory of each card will contain an NDEF project record with: - format_version - project_id - project_label - project_path - metadata_version - card_revision - provisioning_timestamp - record_checksum The UID is a manufacturer-programmed hardware identity and is not overwritten. Existing-card overwrite means replacing the NDEF/project record in writable user memory. Blank-card initialization: 1. Read the UID. 2. Confirm that the UID is not already registered. 3. Select or enter project information. 4. Write the NDEF record. 5. Read the record back. 6. Verify the project ID, revision, and checksum. 7. Add the UID-to-project binding to the local authorization database. 8. Generate a provisioning audit event. Existing-card overwrite: 1. Read and display the existing record. 2. Require administrator confirmation and an overwrite reason. 3. Increment the card revision. 4. Write and read back the new NDEF record. 5. Verify its checksum and fields. 6. Update the local binding. 7. Generate an overwrite audit event. If writing or verification fails, the allowlist and cloud state are not updated and the card enters a WRITE_FAILED or QUARANTINED state. ## Software Authorization Subsystem The host control hub will use a UID-to-project allowlist and operator confirmation. The local authorization database will maintain card_uid, project_id, authorized_at, authorized_by, card_revision, last_seen_revision, card_status, last_write_status, and last_sync_revision. Authorization rules: - Unknown UIDs cannot select or start a runtime. - Blank-card initialization requires administrator confirmation. - Existing-card overwrite requires administrator confirmation and old-record review. - The runtime adapter may report runtime state but may not overwrite NFC cards. - Acknowledgement requires host-side operator confirmation. - Duplicate project bindings are rejected until resolved. - A failed write does not update the allowlist or cloud state. NTAG213/215 password protection may be enabled as an additional tag-level protection layer, but it does not replace host-side authorization. ## Cloud/GitHub Synchronization and Versioned State The control hub will synchronize the NFC system state to a private GitHub repository using the GitHub repository contents API or an equivalent Git interface. Each legal provisioning, overwrite, insertion, removal, acknowledgement, and runtime state change produces a local event and a versioned state update. The repository will contain files similar to: - state/current_state.json - state/cards.json - state/project_bindings.json - state/permissions.json - state/system_config.json - audit/YYYY-MM-DD.jsonl The state snapshot will include schema_version, state_revision, device_id, slots, cards, last_event_id, and generated_at. Each audit event will include event_id, event_type, slot_id, card_uid, project_id, old_revision, new_revision, operator, timestamp, and device_state. Synchronization behavior: - The local control hub is the real-time source of truth. - Events are written to a durable local queue before upload. - Network availability causes pending state revisions to be committed in order. - Network loss does not stop local NFC, mechanical, or runtime operation. - A remote/local revision mismatch produces SYNC_CONFLICT and requires administrator resolution. - Synchronization failure never directly commands a card movement. The GitHub repository will be private. A fine-grained GitHub token with access only to the required repository will be stored in the host computer's secret store. No token, credential, or project file will be stored on an NFC card, in firmware, or in the repository state data. ## Card Presence and Position Sensing Each slot will use three optical interrupters: - Vishay TCST2103 for card-present detection. - Vishay TCST2103 for raised-position detection. - Vishay TCST2103 for lowered-position detection. The three-slot prototype therefore uses nine sensors. The controller will distinguish card_absent, card_present, card_raised, card_lowered, position_transition, and mechanical_fault. Position will not be inferred only from servo angle or timeout. ## Mechanical Card-Lifting Subsystem Each slot will contain: - One MG90S metal-gear micro servo. - One spring mechanism. - One servo-driven cam/latch mechanism. - Card guide rails. - Raised and lowered mechanical hard stops. The spring biases the card toward the raised position. The servo cam/latch holds it in the lowered position while the runtime is operating normally. Position sensors verify the final state. The formal prototype target is three complete slots. The frame and electrical interfaces will be designed for possible expansion to six slots. ## Embedded Controller and State Machine The main controller will be an ESP32-S3-MINI-1. It will provide USB Serial/JTAG, SPI or I2C for NFC readers, PWM for servos, GPIO inputs for sensors, I2C for the OLED, and control signals for LEDs and the buzzer. The state machine will include EMPTY, CARD_DETECTED, UNKNOWN_CARD, PROVISIONING, AUTHORIZED, SELECTED, RUNNING, ATTENTION_REQUIRED, BLOCKED, ACKNOWLEDGED, MOVING_UP, MOVING_DOWN, RELEASED, WRITE_FAILED, SYNC_PENDING, SYNC_CONFLICT, and MECHANICAL_FAULT. ## User Feedback Each slot will use one WS2812B RGB LED. The device will also use one SSD1306 0.96-inch I2C OLED, one 5 V active buzzer, and an N-channel MOSFET buzzer driver. Suggested indications: - Released: LED off. - Selected: blue. - Running: green. - Attention required: flashing red. - Blocked: flashing orange. - Acknowledged: yellow. - Unknown card: flashing purple. - Write failed: flashing white. - Mechanical fault: alternating red and white. The OLED will display the slot number, project label, runtime state, card revision, provisioning or overwrite status, GitHub synchronization status, attention reason, and error code. ## USB-C Power The device will use USB-C 5 V power and will not use a battery. The input will feed a protected servo 5 V rail and a regulated 3.3 V logic rail. The custom PCB will include a USB-C connector, CC resistors, fuse or resettable overcurrent protection, TVS protection, servo bulk capacitance, local ceramic bypass capacitors, separate servo power routing, and 5 V/3.3 V test points. The power subsystem must prevent simultaneous servo startup from causing an MCU reset, NFC communication failure, OLED corruption, or false sensor events. ## Host Communication and Runtime Integration The device will use a documented USB serial protocol. Events will include CARD_INSERTED, CARD_REMOVED, CARD_PROVISIONED, CARD_OVERWRITTEN, CARD_WRITE_VERIFIED, CARD_WRITE_FAILED, UNKNOWN_CARD, RUNTIME_START, RUNTIME_RUNNING, RUNTIME_COMPLETE, ATTENTION_REQUIRED, BLOCKED, ACKNOWLEDGED, RESUME, MECHANICAL_FAULT, SYNC_PENDING, SYNC_COMPLETE, and SYNC_CONFLICT. Messages will include slot_id, card_uid, project_id, event_type, runtime_state, card_revision, acknowledgement_state, timestamp, and error_code. The runtime adapter will connect to Codex pre-run and post-run hooks for the final demonstration. A host simulator will generate the same protocol events for repeatable tests. # Criterion For Success - Three slots simultaneously identify three different NFC cards. - A blank card is initialized with a valid NDEF project record. - An existing card is overwritten only after administrator confirmation. - Every successful write is followed by read-back verification. - Unknown UIDs cannot select or start a runtime. - Unconfirmed writes are rejected. - The runtime adapter cannot directly overwrite cards. - Card revision increments after every successful overwrite. - Failed writes do not update the allowlist or cloud state. - GitHub stores the current NFC system state in a private repository using versioned JSON snapshots. - Provisioning, overwrite, and runtime state changes produce traceable cloud revisions. - Local NFC and mechanical operation continue during GitHub or network failure. - Pending local changes synchronize after network recovery. - Remote/local revision conflicts are detected rather than silently overwritten. - GitHub tokens do not appear on cards, in firmware, or in repository state files. - Card insertion and removal detection accuracy is at least 98%. - Adjacent slots do not incorrectly identify each other's cards. - An attention event causes the corresponding card to begin rising within two seconds. - An acknowledgement or resume command causes the corresponding card to complete lowering within two seconds. - The system completes at least 100 raise/lower cycles without a jam or lost state. - Three servos can actuate simultaneously without resetting the MCU or losing NFC, OLED, or USB communication. - The host simulator can send at least 1,000 events without slot/project mismatches. - Removing a card prevents old runtime events from controlling a subsequently inserted card. - The system operates from USB-C power without a battery. - NFC cards and GitHub state files contain no credentials, project files, or other sensitive information. # Verification Plan ## NFC and Authorization Tests Test blank-card provisioning, NDEF encoding, existing-card overwrite, revision increments, checksum verification, read-back verification, tag password protection, unknown UID rejection, duplicate bindings, unauthorized writes, and write-failure rollback. ## GitHub Synchronization Tests Test initial synchronization, repeated synchronization, offline queueing, network recovery, unavailable repository handling, missing credentials, commit or snapshot verification, remote revision conflicts, and restoration from a previous state snapshot. ## Hardware Tests Test NFC read range, antenna isolation, adjacent-reader interference, optical sensors, servo actuation, RGB LEDs, OLED, buzzer, USB-C input, 5 V servo rail, 3.3 V logic rail, and simultaneous servo startup. ## Integrated Tests Test provisioning, card selection, runtime start, normal running, attention-required state, acknowledgement, card overwrite, card removal, release, and synchronization of every resulting state. ## Full-System Tests Test all three slots in parallel, simultaneous servo movement, power disturbances, repeated NFC writes, long mechanical cycling, offline operation, queued GitHub synchronization, and conflict recovery. # Optional DLC: Portable NFC Project Key and Context Synchronization This section is intentionally separate from the base project. It is not required for the three-slot prototype to succeed. The DLC would extend the card record with required_context_id, context_revision, agent_configuration_revision, verified_manifest_hash, and last_verified_sync_revision. When a card is inserted into a device connected to another computer, the control hub could check whether the required project context and agent configuration are locally available and current. If they are missing or outdated, it could retrieve a context bundle from GitHub or another designated server, verify its manifest and checksum, and write the verified revision back to the NFC card. The DLC is included so the course staff can judge whether the base runtime selector already has sufficient scope and complexity. If the base project is sufficient, the DLC remains future work. If additional system-level complexity is needed, a limited part of the DLC can be implemented after the base hardware and control system are stable. # Scope and Safety Notes - The base project is a three-slot prototype; six slots are an expansion target. - The device uses USB-C power and no rechargeable battery. - NFC cards do not store credentials, project files, or sensitive data. - GitHub synchronization uses a private repository and host-side secret storage. - GitHub is not required for real-time mechanical control. - Mechanical hard stops, sensor feedback, protected power distribution, and explicit fault states reduce risk from stalled actuators or unexpected movement. |
|||||