Initial commit: HereIAm mouse movement monitor
- Complete macOS application with PyQt5 GUI - Smart mouse monitoring with configurable timing - System menu bar integration with adaptive theming - Comprehensive build system with PyInstaller - Professional DMG creation for distribution - Full documentation and testing scripts
This commit is contained in:
Jerico Thomas
240
README.md
Normal file
240
README.md
Normal file
@@ -0,0 +1,240 @@
|
||||
# HereIAm - Mouse Movement Monitor
|
||||
|
||||
## Overview
|
||||
HereIAm is a sophisticated macOS application that runs discretely in the system menu bar. It intelligently monitors mouse activity and automatically moves the cursor to prevent system inactivity when needed. The application features a clean PyQt5-based interface with adaptive theming and comprehensive logging.
|
||||
|
||||
## Features
|
||||
|
||||
### Core Functionality
|
||||
- **Smart Mouse Monitoring**: Tracks mouse position and automatically moves cursor after a configurable period of inactivity
|
||||
- **System Menu Bar Integration**: Runs as a native macOS menu bar application with context menu controls
|
||||
- **Adaptive Icon Theming**: Automatically adjusts icons based on system dark/light mode
|
||||
- **Thread-Safe Operation**: Mouse monitoring runs in a separate thread for responsive UI
|
||||
|
||||
### User Interface
|
||||
- **Right-click Context Menu**: Easy enable/disable controls with visual status indicators
|
||||
- **Double-click Toggle**: Quick enable/disable by double-clicking the menu bar icon
|
||||
- **About Dialog**: Displays application information and version details
|
||||
- **Status Display**: Real-time status indication in the context menu
|
||||
|
||||
### Advanced Features
|
||||
- **Comprehensive Logging**: Detailed logging with configurable levels (DEBUG/INFO)
|
||||
- **Error Handling**: Robust error handling and recovery mechanisms
|
||||
- **Configuration Management**: Centralized configuration with easy customization
|
||||
- **System Integration**: Proper macOS system tray integration with fail-safes
|
||||
|
||||
## Installation
|
||||
|
||||
### Prerequisites
|
||||
- macOS (tested on macOS 10.14+)
|
||||
- Python 3.8 or higher
|
||||
- System with menu bar/system tray support
|
||||
|
||||
### Setup Steps
|
||||
|
||||
1. **Clone the repository:**
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd HereIAm
|
||||
```
|
||||
|
||||
2. **Create a virtual environment (recommended):**
|
||||
```bash
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
```
|
||||
|
||||
3. **Install dependencies:**
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
4. **Install as package (optional):**
|
||||
```bash
|
||||
pip install -e .
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### Running the Application
|
||||
|
||||
**From source:**
|
||||
```bash
|
||||
python src/main.py
|
||||
```
|
||||
|
||||
**If installed as package:**
|
||||
```bash
|
||||
hereiam
|
||||
```
|
||||
|
||||
### Using the Application
|
||||
|
||||
1. **Launch**: The application will appear in your menu bar with an icon
|
||||
2. **Enable/Disable**: Right-click the icon to access the context menu
|
||||
3. **Quick Toggle**: Double-click the icon for instant enable/disable
|
||||
4. **Status Monitoring**: The icon changes to indicate current state:
|
||||
- ✅ **Enabled**: Green icon when mouse monitoring is active
|
||||
- ❌ **Disabled**: Gray icon (theme-aware) when monitoring is off
|
||||
|
||||
### Menu Options
|
||||
- **Status**: Shows current monitoring state
|
||||
- **Enable HereIAm**: Starts mouse movement monitoring
|
||||
- **Disable HereIAm**: Stops mouse movement monitoring
|
||||
- **About HereIAm**: Application information and version
|
||||
- **Quit**: Cleanly exits the application
|
||||
|
||||
## Configuration
|
||||
|
||||
### Main Settings (`src/config.py`)
|
||||
```python
|
||||
WAITTIME = 240 # Wait time in seconds before moving mouse (default: 4 minutes)
|
||||
MovePx = 10 # Pixels to move mouse (default: 10px)
|
||||
StartEnabled = True # Start with monitoring enabled (default: True)
|
||||
DEBUG = False # Enable debug logging (default: False)
|
||||
```
|
||||
|
||||
### Logging Configuration
|
||||
- **Log Location**: `logs/hereiam.log`
|
||||
- **Log Rotation**: Automatic (when DEBUG mode is enabled)
|
||||
- **Log Levels**: INFO (default) or DEBUG (when DEBUG=True)
|
||||
|
||||
## Dependencies
|
||||
|
||||
### Core Runtime Dependencies
|
||||
- **PyQt5** (≥5.15.0): GUI framework and system tray integration
|
||||
- **pyautogui** (≥0.9.54): Mouse movement and position detection
|
||||
- **pyobjc-framework-Cocoa** (≥9.0): macOS system integration
|
||||
- **pyobjc-framework-Quartz** (≥9.0): macOS graphics and display APIs
|
||||
|
||||
### Development Dependencies (Optional)
|
||||
- **pytest** (≥7.0.0): Testing framework
|
||||
- **black** (≥22.0.0): Code formatting
|
||||
- **flake8** (≥4.0.0): Code linting
|
||||
|
||||
## Project Structure
|
||||
```
|
||||
HereIAm/
|
||||
├── src/
|
||||
│ ├── main.py # Application entry point and main GUI logic
|
||||
│ ├── mouse_mover.py # Mouse monitoring and movement logic
|
||||
│ ├── config.py # Configuration and logging setup
|
||||
│ └── utils.py # Utility functions and safety features
|
||||
├── assets/
|
||||
│ ├── Enabled.icns # Icon for enabled state
|
||||
│ ├── Disabled-Light.icns # Icon for disabled state (light theme)
|
||||
│ └── Disabled-Dark.icns # Icon for disabled state (dark theme)
|
||||
├── logs/ # Application logs (created at runtime)
|
||||
├── requirements.txt # Python dependencies
|
||||
├── setup.py # Package installation configuration
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
## Technical Details
|
||||
|
||||
### Architecture
|
||||
- **Main Application** (`main.py`): PyQt5-based GUI with system tray integration
|
||||
- **Mouse Monitor** (`mouse_mover.py`): Threaded mouse position tracking and automatic movement
|
||||
- **Configuration** (`config.py`): Centralized settings and logging configuration
|
||||
- **Utilities** (`utils.py`): Safety features and error handling for mouse operations
|
||||
|
||||
### How It Works
|
||||
1. **Monitoring**: The application continuously tracks mouse position in a background thread
|
||||
2. **Timer Management**: A countdown timer resets whenever mouse movement is detected
|
||||
3. **Automatic Movement**: When the timer expires, the mouse is moved slightly and returned to position
|
||||
4. **User Feedback**: The menu bar icon and status reflect the current monitoring state
|
||||
|
||||
### Safety Features
|
||||
- **Bounds Checking**: Mouse movements are constrained to screen boundaries
|
||||
- **Error Recovery**: Comprehensive exception handling prevents crashes
|
||||
- **Graceful Shutdown**: Clean thread termination and resource cleanup
|
||||
- **Fail-Safe Integration**: PyAutoGUI safety features configured appropriately
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Application doesn't appear in menu bar:**
|
||||
- Ensure system tray is available on your system
|
||||
- Check that PyQt5 is properly installed
|
||||
- Verify you have necessary permissions for GUI applications
|
||||
|
||||
**Mouse movement not working:**
|
||||
- Check that accessibility permissions are granted to Terminal/Python
|
||||
- Verify pyautogui installation: `python -c "import pyautogui; print('OK')"`
|
||||
- Review logs in `logs/hereiam.log` for error details
|
||||
|
||||
**Icons not displaying:**
|
||||
- Verify all `.icns` files are present in the `assets/` directory
|
||||
- Check file permissions on the assets folder
|
||||
- Enable DEBUG mode in config.py for detailed icon loading logs
|
||||
|
||||
### Debugging
|
||||
1. Enable debug mode in `src/config.py`: `DEBUG = True`
|
||||
2. Run from terminal to see console output
|
||||
3. Check `logs/hereiam.log` for detailed operation logs
|
||||
4. Use Activity Monitor to verify the application is running
|
||||
|
||||
## Development
|
||||
|
||||
### Building from Source
|
||||
```bash
|
||||
# Setup development environment
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
|
||||
# Run in development mode
|
||||
python src/main.py
|
||||
```
|
||||
|
||||
### Building for Distribution
|
||||
|
||||
#### Create macOS .app Bundle
|
||||
```bash
|
||||
# Install build dependencies
|
||||
pip install -r requirements-build.txt
|
||||
|
||||
# Build the application
|
||||
./build_app.sh
|
||||
```
|
||||
|
||||
This creates `dist/HereIAm.app` - a standalone application bundle.
|
||||
|
||||
#### Create Distribution DMG
|
||||
```bash
|
||||
# Create installer DMG
|
||||
./create_dmg.sh
|
||||
```
|
||||
|
||||
This creates `dist/HereIAm-1.0.0.dmg` ready for distribution.
|
||||
|
||||
#### Full Distribution Workflow
|
||||
```bash
|
||||
# Complete build and package process
|
||||
./build_app.sh && ./create_dmg.sh
|
||||
```
|
||||
|
||||
See [DISTRIBUTION.md](DISTRIBUTION.md) for detailed building, code signing, and distribution instructions.
|
||||
|
||||
### Creating a Standalone App (macOS)
|
||||
```bash
|
||||
# Install PyInstaller
|
||||
pip install pyinstaller
|
||||
|
||||
# Create app bundle
|
||||
pyinstaller --windowed --onefile --add-data "assets:assets" --icon="assets/Enabled.icns" src/main.py
|
||||
```
|
||||
|
||||
## Author & Support
|
||||
|
||||
**Author:** Jerico Thomas
|
||||
**Email:** jerico@tekop.net
|
||||
**Version:** 1.0.0
|
||||
|
||||
## License
|
||||
This project is licensed under the MIT License. See the LICENSE file for details.
|
||||
|
||||
---
|
||||
|
||||
*HereIAm - Keeping your Mac awake, one mouse movement at a time.*
|
||||
Reference in New Issue
Block a user