infoscreen-dev/HDMI_CEC_DEV_MODE.md

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.

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

# 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

# .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

# .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

# In .env
ENV=production     # Enables CEC
CEC_ENABLED=true

Option 2: Use test scripts

# Test CEC without starting Display Manager
./scripts/test-hdmi-cec.sh         # Interactive menu
./scripts/test-tv-response.sh      # Diagnostic test

Configuration Reference

.env File

# 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

# 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

# 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