WaitKey - Windows Console Keyboard Monitor

A Windows console application that waits for keyboard input with a configurable timeout, displaying a countdown timer and responding to ASCII printable character keypresses.

Features

• Configurable Timeout: Specify wait time in seconds via command line
• Real-time Countdown: Visual countdown display showing remaining time
• ASCII Key Detection: Responds immediately to printable characters (space through tilde)
• Smart Key Filtering: Ignores non-printable keys and extended keys (arrows, function keys, etc.)
• Graceful Interruption: Handles Ctrl+C interrupts properly
• CPU Efficient: Uses minimal system resources during monitoring
• Standalone Executable: No Python installation required on target machines

Usage

WaitKey.exe <timeout_seconds>

Parameters

• timeout_seconds: Positive integer specifying wait time in seconds

Exit Codes

• 0: Timeout expired (no valid key pressed)
• 2: Invalid command line arguments
• 32-126: ASCII code of the pressed printable character
• 130: Ctrl+C interrupt

Examples

WaitKey.exe 10     # Wait for 10 seconds for a keypress
WaitKey.exe 30     # Wait for 30 seconds for a keypress

Installation

Option 1: Download Executable (Recommended)

1. Download WaitKey.exe from the releases page
2. Place it in your desired directory
3. Optionally add the directory to your PATH for global access

Option 2: Build from Source

1. Clone this repository
2. Ensure Python 3.7+ is installed
3. Install PyInstaller: pip install pyinstaller
4. Build executable: python -m PyInstaller --onefile --console --name WaitKey WaitKey.py
5. Find the executable in the dist/ directory

Requirements

• Runtime: Windows operating system (uses msvcrt module)
• Development: Python 3.7+ (for building from source)

Behavior

• Displays a countdown timer showing remaining seconds
• Responds immediately to ASCII printable characters (space through tilde)
• Ignores non-printable keys and extended keys (arrows, function keys, etc.)
• Can be interrupted with Ctrl+C
• Uses controlled polling intervals (20-50ms) for CPU efficiency
• Employs monotonic time measurement for accuracy

Technical Details

Architecture

• Single-threaded, event-loop architecture
• Polling-based keyboard detection using msvcrt
• Real-time countdown display with 1-second update intervals
• Efficient sleep cycles between polling operations

Dependencies

• Standard Library Only: sys, time, msvcrt
• No External Dependencies: Fully self-contained

Key Components

• ArgumentParser: Command line validation and parsing
• KeyboardMonitor: ASCII key detection and classification
• TimeoutManager: Countdown display and timing management
• ExitHandler: Proper exit code management

Development

Project Structure

WaitKey/
├── WaitKey.py              # Main application source
├── .kiro/specs/            # Feature specifications
│   └── waitkey-timeout/
│       ├── requirements.md # Formal requirements (EARS format)
│       ├── design.md       # Technical design document
│       └── tasks.md        # Implementation task list
├── dist/                   # Distribution files
│   ├── WaitKey.exe        # Standalone executable
│   ├── README.txt         # User documentation
│   └── test.bat           # Test script
└── README.md              # This file

Specification-Driven Development

This project was developed using formal specification methodology:

• Requirements: EARS (Easy Approach to Requirements Syntax) compliant
• Design: Comprehensive technical design with correctness properties
• Implementation: Task-driven development with incremental progress

Author

Mark Oldham

• Version: 1.0
• Build Date: December 30, 2025
• License: MIT

License

MIT License - see the source code for full license text.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly on Windows
5. Submit a pull request

Support

For issues, questions, or feature requests, please open an issue on GitHub.