HDMI-CEC: auto-disable in dev mode + docs/tests synced
README: document dev-mode CEC auto-disable; add testing notes; set CEC_POWER_OFF_WAIT=5 Copilot instructions: add dev-mode CEC behavior and test script guidance test-hdmi-cec.sh: respect ENV=development (skip option 5), explicit .env load, ASCII output, 30s wait display_manager: remove emoji from logs to avoid Unicode errors
This commit is contained in:
165
HDMI_CEC_DEV_MODE.md
Normal file
165
HDMI_CEC_DEV_MODE.md
Normal file
@@ -0,0 +1,165 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user