# BitWands: Interactive CS Learning System ## Project Requirements Document **Project:** BitWands - Educational Binary Representation System **Date:** December 2024 **Version:** 1.0 --- ## 1. Functional Requirements These define what the system must do—its core behaviors, functions, and tasks. ### 1.1 Wand Device Requirements **FR-1.1:** Each wand **must** detect its orientation (raised vs. lowered) and report the corresponding binary state (1 for raised, 0 for lowered) to the hub within 100ms of a state change. **FR-1.2:** Each wand **must** display its current state via LED color: green when in the raised/1 state, red when in the lowered/0 state. **FR-1.3:** Each wand **must** transmit its current state to the hub at least every 200ms to maintain synchronization. **FR-1.4:** Each wand **must** have a unique device ID (0-7) that identifies its bit position within the byte. **FR-1.5:** The wand firmware **must** enter a low-power sleep mode after 5 minutes of inactivity (no orientation changes detected). ### 1.2 Hub Requirements **FR-2.1:** The hub **must** receive state packets from all eight wands and aggregate them into a single byte value. **FR-2.2:** The hub **must** transmit the aggregated byte value to the game software via USB serial communication at a minimum rate of 10 times per second. **FR-2.3:** The hub **must** detect when a wand stops responding (no packet received for >500ms) and report this condition to the game software. **FR-2.4:** The hub **must** support pairing/association with exactly eight wands, maintaining their assigned bit positions. ### 1.3 Game Software Requirements **FR-3.1:** The game software **must** display the target hexadecimal value that players need to match. **FR-3.2:** The game software **must** display the current binary and hexadecimal values represented by the wand states in real-time (updated at least 10 times per second). **FR-3.3:** In 4v4 competitive mode, the software **must** detect when a team of four wands correctly represents the target hex digit (0-F) and award points within 200ms. **FR-3.4:** In 8-bit cooperative mode, the software **must** detect when all eight wands correctly represents the target byte value (00-FF) and advance to the next challenge. **FR-3.5:** The game software **must** provide a training mode that displays current values without time pressure or scoring. **FR-3.6:** The game software **must** maintain a score/time record for each game session and display results at the end. **FR-3.7:** The proof-of-concept game software **must** run in a terminal/console environment using terminal graphics (no GUI required for initial version). --- ## 2. Non-Functional Requirements (NFRs) These define how well the system must perform its functions. ### 2.1 Performance **NFR-1.1:** The system latency from wand motion to visual feedback on the computer screen **must** be less than 300ms (target: <250ms). **NFR-1.2:** The radio communication system **must** achieve >95% packet delivery rate at distances up to 10 meters in a typical classroom environment. **NFR-1.3:** The orientation sensor **must** correctly distinguish between raised and lowered states with >98% accuracy, including during rapid transitions. **NFR-1.4:** The system **must** support all eight wands operating simultaneously without packet collisions causing more than 5% packet loss. ### 2.2 Reliability **NFR-2.1:** Each wand **must** operate for a minimum of 2 hours of continuous active gameplay on a single battery charge. **NFR-2.2:** The wands **must** maintain stable radio communication for the duration of a 45-minute classroom session without requiring reset or intervention. **NFR-2.3:** The system **must** recover gracefully from temporary radio interference, resuming normal operation within 2 seconds after interference ceases. ### 2.3 Efficiency & Power **NFR-3.1:** Each wand **must** consume less than 100mA average current during active operation (excluding brief LED pulses). **NFR-3.2:** Each wand **must** consume less than 50µA in sleep mode. **NFR-3.3:** The LED indicators **must** be clearly visible from 5 meters in typical classroom lighting conditions while consuming <20mA per LED. ### 2.4 Usability **NFR-4.1:** The orientation threshold for detecting raised vs. lowered **must** be forgiving enough that students don't need to hold wands perfectly vertical/horizontal (±20° tolerance acceptable). **NFR-4.2:** The wand enclosure **must** be comfortable to hold for a 10-15 minute game session for users with hand sizes ranging from small (child) to large (adult). **NFR-4.3:** The terminal-based game display **must** be clearly readable on a laptop/desktop screen with standard terminal fonts at typical viewing distances (50-70cm). --- ## 3. Technical & Physical Requirements These specify the technical constraints, physical attributes, and interfaces. ### 3.1 Physical Constraints **TR-1.1:** Each wand, including battery and enclosure, **must** weigh no more than 200 grams. **TR-1.2:** Each wand **must** fit within an enclosure no larger than 30cm length × 5cm diameter (similar to a large flashlight or relay baton). **TR-1.3:** The wand enclosure **must** have a clearly defined "up" orientation (visual or tactile indicator at the tip). **TR-1.4:** The hub **must** fit within a 10cm × 10cm × 5cm enclosure to be easily placed on a desk or table. ### 3.2 Interface Requirements **TR-2.1:** The hub **must** communicate with the game software via USB serial at 115200 baud, using a simple ASCII protocol for easy debugging. **TR-2.2:** Each wand **must** use the RFM69HCW radio module operating in the 915 MHz ISM band (for US operation). **TR-2.3:** The radio communication protocol **must** use addressed packets with a simple checksum for error detection. **TR-2.4:** Each wand **must** include a USB port (USB-C preferred) for battery charging and firmware updates. **TR-2.5:** The game software **must** run on Windows, macOS, and Linux without requiring special drivers beyond standard USB serial support. ### 3.3 Component Specifications **TR-3.1:** The microcontroller **must** be the Raspberry Pi RP2040 or compatible ARM Cortex-M0+ processor. **TR-3.2:** The orientation sensor **must** provide at least 2-axis tilt detection with <10° resolution, OR the system must use a custom-designed tilt switch circuit. **TR-3.3:** The battery **must** be a rechargeable lithium-ion or lithium-polymer cell with built-in protection circuitry. **TR-3.4:** All wand PCBs **must** use identical designs to simplify manufacturing and maintenance. **TR-3.5:** The LED indicators **must** use RGB LEDs (WS2812B or similar) to allow future expansion of color coding beyond red/green. ### 3.4 Firmware & Software Requirements **TR-4.1:** The wand and hub firmware **must** be written in Zig with a custom HAL layer generated from a data-driven build system (no vendor SDK dependencies). **TR-4.2:** The firmware **must** use a custom linker script defining the RP2040 memory layout from scratch. **TR-4.3:** The build system **must** use Zig's build system exclusively (no Make or CMake) and be reproducible on Linux, macOS, and Windows. **TR-4.4:** The HAL **must** be generated from a custom data-driven system that produces hardware abstraction code from configuration data. **TR-4.5:** The proof-of-concept game software **must** be written in Zig and run in a terminal environment. **TR-4.6:** The terminal interface **must** support basic text formatting and color output for displaying binary states and game information. --- ## 4. Constraints These are overarching limitations that restrict the project's options. ### 4.1 Cost & Schedule **C-1.1:** The total Bill of Materials (BOM) for the complete system (8 wands + hub) **must not** exceed $300. **C-1.2:** Individual wand BOM cost **must not** exceed $27 per unit to stay within overall budget. **C-1.3:** The first functional prototype (minimum 2 wands + hub) **must** be operational by Week 10 of the project timeline. **C-1.4:** Complete system (8 wands + hub + game software) **must** be ready for user testing by Week 14. **C-1.5:** Final presentation-ready system **must** be complete by Week 16. ### 4.2 Regulatory & Safety **C-2.1:** The radio transmitters **must** operate within FCC Part 15 rules for unlicensed transmitters in the 902-928 MHz band (or appropriate band for operating region). **C-2.2:** The battery charging circuits **must** include overcurrent, overvoltage, and thermal protection to prevent hazardous conditions. **C-2.3:** All exposed electronics **must** be adequately insulated to prevent shock hazards during normal use. **C-2.4:** The wands **must** be designed for safe use by children aged 10+ without sharp edges or pinch points. ### 4.3 Maintainability & Documentation **C-3.1:** The wand design **must** allow battery replacement without soldering (connector-based). **C-3.2:** The PCB design **must** include test points for all critical signals (power, SPI, radio control lines) to facilitate debugging. **C-3.3:** All source code **must** be documented with comments explaining hardware interactions, state machines, and protocol details. **C-3.4:** A comprehensive design document **must** be created explaining the bare-metal firmware approach using Zig, custom data-driven HAL generation system, linker script configuration, and Zig build system setup. ### 4.4 Educational Requirements **C-4.1:** The project **must** include original design work in at least two major disciplines: Analog, Digital, Microcontrollers, Power, or Communications. **C-4.2:** At least 50% of the project **must** involve electrical/electronic design (the remainder may be software). **C-4.3:** The project **must** demonstrate significant design work beyond assembling pre-built modules (custom data-driven HAL generation system, linker scripts, protocol design, PCB layout). **C-4.4:** All design files, source code, and documentation **must** be suitable for release under open-source licenses (CERN OHL for hardware, MIT/Apache for software, CC BY-SA for documentation). ### 4.5 Environmental **C-5.1:** The wands **must** operate reliably in typical indoor classroom temperatures (15°C to 30°C). **C-5.2:** The wands **must** survive accidental drops from table height (1 meter) onto a hard floor without permanent damage or safety hazards. **C-5.3:** The battery system **must** be safe for storage and operation in the temperature range of 0°C to 40°C. --- ## 5. Verification & Testing Criteria ### 5.1 Functional Testing - **Test FR-1.1:** Measure orientation detection response time using oscilloscope/logic analyzer. Success: <100ms from motion to state change. - **Test FR-1.2:** Visual inspection of LED colors in raised/lowered states. Success: Correct color displayed, visible from 5m. - **Test FR-2.1:** Log hub output while manipulating all 8 wands. Success: Correct byte value computed from individual bit states. - **Test FR-3.2:** Measure game display update rate. Success: ≥10 updates per second with <300ms total latency. ### 5.2 Performance Testing - **Test NFR-1.2:** Operate system at various distances, log packet loss rate. Success: <5% loss at 10m. - **Test NFR-2.1:** Continuous operation test with current measurement. Success: ≥2 hours on single charge. - **Test NFR-1.4:** Operate all 8 wands simultaneously for 30 minutes. Success: <5% packet loss overall. ### 5.3 Physical Testing - **Test TR-1.1:** Weigh completed wand. Success: ≤200g. - **Test C-5.2:** Drop test from 1m onto concrete. Success: No permanent damage, all functions work after test. ### 5.4 User Testing - **Test NFR-4.2:** Have 5-10 users of varying ages play for 10 minutes. Success: No complaints of discomfort or difficulty holding wands. - **Educational Effectiveness:** Pre/post quiz on binary/hex concepts. Success: Measurable improvement in understanding. --- ## 6. Success Metrics The project will be considered successful when: 1. All eight wands reliably communicate with the hub 2. The game software correctly interprets and displays wand states 3. System latency (wand motion to screen update) is <300ms 4. Battery life exceeds 2 hours of active gameplay 5. User testing demonstrates that students understand binary/hex concepts better after using the system 6. Complete documentation of design process is available for educational use 7. All project deliverables are complete and ready for open-source release --- ## 7. Out of Scope (Explicitly NOT Required) - Bluetooth or WiFi connectivity (using dedicated radio module instead) - Mobile app support (desktop software only for initial version) - Graphical user interface (terminal-based proof-of-concept only; GUI is future work) - Advanced game modes beyond those specified (stretch goals only) - Waterproofing or outdoor use capability - Support for more than 8 wands (future extension) - Integration with learning management systems (LMS) - Commercial packaging or manufacturing-ready design - Projector/large display optimization (terminal display is sufficient for proof-of-concept)