infoscreen-dev/HDMI_CEC_DEV_MODE.md

# HDMI-CEC Development Mode Behavior

## Overview
HDMI-CEC TV control is **automatically disabled** in development mode to prevent constantly switching the TV on/off during testing and development work.

## How It Works

### Automatic Behavior
```python
# In display_manager.py
if ENV == "development":
    CEC_ENABLED = False  # Override user setting
```

### Configuration Priority
1. **Development Mode** (`ENV=development`): CEC always **OFF** (regardless of `CEC_ENABLED` setting)
2. **Production Mode** (`ENV=production`): CEC respects `CEC_ENABLED` setting

### Log Messages
- **Development**: `🔧 Development mode: HDMI-CEC automatically disabled (TV control off)`
- **Production + Enabled**: `📺 HDMI-CEC enabled: TV control active (device: 0)`
- **Production + Disabled**: `📺 HDMI-CEC disabled in configuration`

## Why Local Configuration?

This is **local configuration** (not server-controlled) because:

### ✅ Best Practice Reasons
1. **Hardware-specific** - TV control is a local hardware concern
2. **Independent operation** - Works without server connection
3. **Developer workflow** - Fast toggle without server changes
4. **Existing pattern** - Follows established `ENV` variable pattern
5. **No deployment needed** - Change `.env` and restart

### ❌ Why NOT Server-Controlled?
1. Would require server deployment for local dev changes
2. Adds network dependency to hardware feature
3. Complicates client logic (need to fetch setting)
4. Server shouldn't control local hardware behavior
5. Breaks offline/standalone operation

## Usage

### Development Workflow
```bash
# .env file
ENV=development    # CEC automatically disabled
CEC_ENABLED=true   # Ignored in dev mode

# Start Display Manager
./scripts/start-display-manager.sh
# Output: 🔧 Development mode: HDMI-CEC automatically disabled
```

### Production Deployment
```bash
# .env file
ENV=production     # CEC respects setting
CEC_ENABLED=true   # TV control active

# Start Display Manager
./scripts/start-display-manager.sh
# Output: 📺 HDMI-CEC enabled: TV control active (device: 0)
```

### Force Enable CEC in Development (for testing)
If you need to test CEC functionality during development:

**Option 1: Temporarily set production mode**
```bash
# In .env
ENV=production     # Enables CEC
CEC_ENABLED=true
```

**Option 2: Use test scripts**
```bash
# Test CEC without starting Display Manager
./scripts/test-hdmi-cec.sh         # Interactive menu
./scripts/test-tv-response.sh      # Diagnostic test
```

## Configuration Reference

### .env File
```bash
# Environment mode
ENV=development    # or 'production'

# HDMI-CEC TV Control
# NOTE: Automatically DISABLED when ENV=development
CEC_ENABLED=true
CEC_DEVICE=0
CEC_TURN_OFF_DELAY=30
CEC_POWER_ON_WAIT=5
CEC_POWER_OFF_WAIT=5
```

## Testing CEC Functionality

### Without Starting Display Manager
```bash
# Interactive testing menu
./scripts/test-hdmi-cec.sh

# Diagnostic test with detailed feedback
./scripts/test-tv-response.sh

# Manual commands
echo "on 0" | cec-client -s -d 1      # Turn TV on
echo "standby 0" | cec-client -s -d 1 # Turn TV off
echo "pow 0" | cec-client -s -d 1     # Check status
```

### With Display Manager
```bash
# Temporarily enable production mode
ENV=production ./scripts/start-display-manager.sh

# Or edit .env first
vim .env  # Set ENV=production
./scripts/start-display-manager.sh
```

## Architecture Decision

### Chosen: Local Configuration
- ✅ Simple and maintainable
- ✅ Fast development workflow
- ✅ No server dependency
- ✅ Follows project patterns

### Rejected: Server-Controlled
- ❌ Adds complexity
- ❌ Requires network/server
- ❌ Slower iteration
- ❌ Wrong abstraction level

### Comparison

| Aspect | Local Config | Server Config |
|--------|-------------|---------------|
| Toggle speed | Instant (restart) | Requires server deployment |
| Network dependency | None | Required |
| Offline operation | ✅ Works | ❌ Breaks |
| Development workflow | ✅ Simple | ❌ Complex |
| Hardware abstraction | ✅ Correct | ❌ Wrong level |
| Server concern | ❌ No | ✅ Yes |

## Related Files

- **Implementation**: `src/display_manager.py` (lines 48-76)
- **Configuration**: `.env` (CEC section)
- **Testing**: `scripts/test-hdmi-cec.sh`, `scripts/test-tv-response.sh`
- **Documentation**: `HDMI_CEC_SETUP.md`, `HDMI_CEC_IMPLEMENTATION.md`

## Summary

🎯 **HDMI-CEC is automatically disabled in development mode** to prevent TV switching during testing.

🔧 **To test CEC**: Use test scripts or temporarily set `ENV=production`

📺 **In production**: CEC respects `CEC_ENABLED` setting and works as expected

🏗️ **Architecture**: Local configuration is best practice for hardware-specific behavior