prezenta_work/README_DEPENDENCIES.md

# Prezenta App - Robust Dependency Management System

## Overview
The app.py has been updated to include a comprehensive, self-contained dependency management system that automatically checks and installs required packages from a local repository. This makes the system completely offline-capable and resilient to network issues.

## Key Features

### 🔧 **Automatic Dependency Installation**
- **Self-contained**: No need for separate launcher scripts or shell scripts
- **Offline capability**: Installs packages from local `./Files/reposytory` directory
- **Smart detection**: Checks if packages are already installed before attempting installation
- **Fallback mechanisms**: Multiple installation methods (pip, apt, local wheels)

### 🛡️ **Robust Error Handling**
- **Network resilience**: Handles socket errors gracefully with file-based fallbacks
- **Import safety**: Safe import functions that don't crash the app
- **Graceful degradation**: App continues to work even if some optional features fail
- **Comprehensive logging**: All operations are logged for debugging

### 📦 **Supported Packages**
The system automatically manages these packages:
- `rdm6300` - RFID reader library (critical)
- `requests` - HTTP library (critical) 
- `aiohttp` - Async HTTP library (optional)
- `flask` - Web server for command interface (optional)
- `gpiozero` - GPIO control (falls back to dummy if not available)
- All required dependencies (urllib3, certifi, charset_normalizer, etc.)

## How It Works

### 1. **Startup Dependency Check**
When the app starts, it:
1. Checks each required package using `importlib.util.find_spec()`
2. Identifies missing packages
3. Attempts installation from local wheel files in `./Files/reposytory`
4. Falls back to pip/apt if needed
5. Continues execution even if some packages fail to install

### 2. **Safe Import System**
```python
def safe_import(module_name, package_name=None):
    """Safely import a module with error handling"""
```
- Imports modules without crashing the app
- Returns None for missing modules
- Allows the app to adapt to available packages

### 3. **Network Error Resilience**
- Device hostname/IP saved to `./data/device_info.txt`
- Automatically loads from file when socket errors occur
- Never crashes due to network resolution issues

### 4. **Graceful Feature Degradation**
- **No Flask**: Command server is disabled with warning
- **No gpiozero**: LED functions become print statements
- **No aiohttp**: Falls back to synchronous requests
- **No network**: Uses cached device information

## Repository Structure

### Required Files in `./Files/reposytory/`:
```
├── rdm6300-0.1.1-py3-none-any.whl
├── requests-2.32.3-py3-none-any.whl
├── aiohttp-3.11.18-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
├── flask-*.whl (optional)
├── urllib3-2.3.0-py3-none-any.whl
├── certifi-2025.1.31-py3-none-any.whl
├── charset_normalizer-3.4.1-py3-none-any.whl
├── idna-3.10-py3-none-any.whl
├── multidict-6.4.3-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
├── aiosignal-1.3.2-py2.py3-none-any.whl
├── frozenlist-1.6.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
├── attrs-25.3.0-py3-none-any.whl
├── yarl-1.20.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
├── aiohappyeyeballs-2.6.1-py3-none-any.whl
└── propcache-0.3.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
```

## Installation Process

### Automatic (Recommended)
Simply run the app - dependencies will be installed automatically:
```bash
cd /home/pi/Desktop/prezenta
python3 app.py
```

### Manual Testing
Test the dependency system:
```bash
cd /home/pi/Desktop/prezenta
python3 test_dependencies.py
```

## Folder Structure

The prezenta folder has been streamlined for maximum simplicity:

```
prezenta/
├── app.py                    # Main application (self-contained)
├── config.py                 # Configuration module  
├── test_dependencies.py      # Testing and validation script
├── README_DEPENDENCIES.md    # This documentation
├── data/                     # Application data
│   ├── device_info.txt       # Network configuration cache (auto-created)
│   ├── idmasa.txt           # Device identifier
│   └── tag.txt              # Backup data
└── Files/                    # Local package repository
    └── reposytory/          # Wheel files for offline installation
        ├── rdm6300-*.whl
        ├── requests-*.whl
        ├── aiohttp-*.whl
        └── ... (all dependencies)
```

### Removed Files (No Longer Needed)
- ~~`launcher.py`~~ - App is now self-launching
- ~~`libraries.sh`~~ - Dependency installation integrated into app.py  
- ~~`check_dependencies.py`~~ - Functionality moved to app.py

## Features Added

### 1. **Self-Installing Dependencies**
- Checks all required packages on startup
- Installs missing packages from local repository
- No external network dependencies for package installation

### 2. **Network Error Recovery**
- Handles `socket.gaierror` gracefully
- Saves working network configuration to file
- Loads from file when network issues occur

### 3. **Modular Feature Set**
- Core RFID functionality always works
- Optional features (web interface, LEDs) degrade gracefully
- Clear status messages for all operations

### 4. **Enhanced Logging**
- Dependency check results logged
- Installation attempts logged
- Network fallback operations logged

## Troubleshooting

### Common Issues

1. **"Repository not found"**
   - Ensure `./Files/reposytory` directory exists
   - Check that wheel files are present

2. **"Permission denied during installation"**
   - Script uses `--break-system-packages` flag
   - May need to run with appropriate permissions

3. **"rdm6300 is required"**
   - This is critical - app will exit if rdm6300 can't be installed
   - Check that `rdm6300-0.1.1-py3-none-any.whl` exists in repository

4. **"Flask not available - Command server disabled"**
   - Non-critical - RFID functionality continues to work
   - Install Flask manually if remote command capability is needed

### Recovery Steps

1. **Check repository**: Ensure all wheel files are present
2. **Test installation**: Run `python3 test_dependencies.py`
3. **Manual install**: Install missing packages manually with pip
4. **Check logs**: Review console output for specific error messages

## Benefits

1. **Zero-configuration deployment**: Just copy files and run
2. **Offline operation**: No internet required after initial setup
3. **Fault tolerance**: Continues working even with partial failures
4. **Easy maintenance**: All dependencies managed automatically
5. **Clear diagnostics**: Detailed status reporting for troubleshooting

## Version History

- **v2.4**: Added robust dependency management and network error handling
- **v2.3**: Added remote command execution capabilities
- **v2.2**: Basic RFID and logging functionality

The system is now production-ready for deployment in environments with limited or no internet connectivity, providing maximum reliability and ease of deployment.