82f43f75ba
shrink root README into a landing page with a docs map and focused contributor guidance add TV_POWER_RUNBOOK as the canonical TV power rollout and canary runbook add CHANGELOG and move project history out of README-style docs refactor src README into a developer-focused guide (architecture, runtime files, MQTT, debugging) prune redundant older HDMI docs and keep a canonical HDMI_CEC_SETUP path update copilot instructions to a high-signal policy format with strict anti-shadow-README design rules align references across docs to current files, scripts, and TV power behavior
168 lines
4.8 KiB
Markdown
168 lines
4.8 KiB
Markdown
# HDMI-CEC Development Mode Behavior
|
|
|
|
This is a focused reference for development-mode behavior. For the canonical HDMI-CEC setup and operator guide, use [HDMI_CEC_SETUP.md](HDMI_CEC_SETUP.md).
|
|
|
|
## 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_FLOW_DIAGRAM.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
|