Configuration Parameter Pattern

Automates the repetitive pattern of adding configuration parameters across Bob The Skull's entire configuration stack.

When to Use

• Adding new configuration parameters to BobConfig.py
• Exposing existing parameters through the web UI
• Creating configurable thresholds, timeouts, or settings
• Extending any configuration page (audio, vision, performance, etc.)

The Full Stack Pattern

Every configuration parameter requires updates in 4 locations:

1. BobConfig.py - Define Parameter

# Add parameter with type hint and comment
VISION_MOTION_THRESHOLD: float = 10.0  # Percentage of frame showing motion (1-20%)

2. config_manager.py - Backend GET

def get_<section>_settings(self) -> Dict:
    return {
        'subsection': {
            'param_name': self.config.PARAM_NAME
        }
    }

3. config_manager.py - Backend SAVE

if 'param_name' in subsection:
    content = re.sub(
        r'PARAM_NAME:\s*<type>\s*=\s*<pattern>',
        f'PARAM_NAME: <type> = {subsection["param_name"]}',
        content
    )
    changes_made.append(f"PARAM_NAME = {subsection['param_name']}")

4. HTML Template - Form Field

<div class="form-group">
    <label for="param_name">Display Name</label>
    <input type="<type>" id="param_name" name="param_name"
           min="X" max="Y" step="Z" required>
    <span class="form-help">Help text explaining the parameter</span>
</div>

5. JavaScript - Populate Form

document.getElementById('param_name').value = settings.subsection.param_name || <default>;

6. JavaScript - Submit Form

subsection: {
    param_name: parseFloat(document.getElementById('param_name').value)
}

Type-Specific Patterns

Boolean Parameters

BobConfig.py:

FEATURE_ENABLED: bool = True  # Enable feature

Regex Pattern:

r'FEATURE_ENABLED:\s*bool\s*=\s*(True|False)'
f'FEATURE_ENABLED: bool = {value}'

HTML:

<div class="checkbox-group">
    <input type="checkbox" id="feature_enabled" name="feature_enabled">
    <label for="feature_enabled">Enable Feature</label>
</div>

JavaScript:

// Populate
document.getElementById('feature_enabled').checked = settings.section.feature_enabled !== false;

// Submit
feature_enabled: document.getElementById('feature_enabled').checked

Integer Parameters

BobConfig.py:

MAX_RETRIES: int = 3  # Maximum retry attempts

Regex Pattern:

r'MAX_RETRIES:\s*int\s*=\s*\d+'
f'MAX_RETRIES: int = {value}'

HTML:

<input type="number" id="max_retries" name="max_retries"
       min="1" max="10" step="1" required>

JavaScript:

// Populate
document.getElementById('max_retries').value = settings.section.max_retries || 3;

// Submit
max_retries: parseInt(document.getElementById('max_retries').value)

Float Parameters

BobConfig.py:

THRESHOLD: float = 0.5  # Detection threshold (0.0-1.0)

Regex Pattern:

r'THRESHOLD:\s*float\s*=\s*[\d.]+'
f'THRESHOLD: float = {float(value)}'

HTML:

<input type="number" id="threshold" name="threshold"
       min="0.0" max="1.0" step="0.1" required>

JavaScript:

// Populate
document.getElementById('threshold').value = settings.section.threshold || 0.5;

// Submit
threshold: parseFloat(document.getElementById('threshold').value)

String Parameters

BobConfig.py:

MODEL_NAME: str = "default"  # Model to use

Regex Pattern:

r'MODEL_NAME:\s*str\s*=\s*"[^"]*"'
f'MODEL_NAME: str = "{value}"'

HTML (dropdown):

<select id="model_name" name="model_name">
    <option value="default">Default</option>
    <option value="advanced">Advanced</option>
</select>

HTML (text input):

<input type="text" id="model_name" name="model_name" required>

JavaScript:

// Populate
document.getElementById('model_name').value = settings.section.model_name || 'default';

// Submit
model_name: document.getElementById('model_name').value

Configuration Pages Reference

Audio Settings

• File: web/templates/config_audio.html
• Backend: config_manager.py - get_audio_settings(), save_audio_settings()
• Sections: general, advanced

Vision Settings

• File: web/templates/config_vision.html
• Backend: config_manager.py - get_vision_settings(), save_vision_settings()
• Sections: general, performance, face_detection, face_identification

System Settings

• File: web/templates/config_system.html
• Backend: config_manager.py - get_system_settings(), save_system_settings()
• Sections: wake_word, stt, llm, tts

Performance Settings

• File: web/templates/config_performance.html
• Backend: config_manager.py - get_performance_settings(), save_performance_settings()
• Sections: state_machine, component_timeouts, other

Eyes Controller Settings

• File: web/templates/config_eyes.html
• Backend: config_manager.py - get_eyes_settings(), save_eyes_settings()
• Sections: discovery, animation

API Keys Settings

• File: web/templates/config_apikeys.html
• Backend: config_manager.py - get_apikeys_settings(), save_apikeys_settings()
• Sections: keys, key_lengths (for display)

Workflow

1. Identify the parameter location in BobConfig.py

   • Find the appropriate section (VISION_*, AUDIO_*, LLM_*, etc.)
   • Determine the correct type (bool, int, float, str)

2. Add to BobConfig.py

   • Use proper type hint
   • Add descriptive comment
   • Choose sensible default value

3. Update config_manager.py GET method

   • Find the appropriate get_*_settings() method
   • Add parameter to the correct subsection dictionary
   • Use self.config.PARAMETER_NAME

4. Update config_manager.py SAVE method

   • Find the appropriate save_*_settings() method
   • Create regex pattern matching the type
   • Add to changes_made list

5. Update HTML template

   • Find the appropriate settings section
   • Add form field with proper input type
   • Include helpful label and description

6. Update JavaScript populate function

   • Find populateForm() or equivalent
   • Add line to set field value from settings
   • Include fallback default value

7. Update JavaScript submit function

   • Find form submission handler
   • Add parameter to the appropriate section
   • Use correct parse function (parseInt, parseFloat, etc.)

Common Pitfalls

1. Type mismatches - Ensure JavaScript parse function matches Python type
2. Missing defaults - Always include || defaultValue in JavaScript populate
3. Regex escaping - Float patterns need [\d.]+, not just \d+
4. Boolean handling - Use !== false for checkboxes, not || true
5. changes_made list - Don't forget to append parameter name to track changes
6. HTML IDs - Must match between form field, populate, and submit JavaScript

Recent Example (2024-12-09)

Added 4 vision detector parameters:

• VISION_MOTION_THRESHOLD: float = 10.0
• VISION_FACE_USE_STABILITY_FILTER: bool = True
• VISION_FACE_STABILITY_SECONDS: float = 2.0
• VISION_FACE_DEBOUNCE_SECONDS: float = 3.0

All integrated into vision configuration page with full get/save/UI support. Total time: ~45 minutes for 4 parameters (would be ~10 minutes with this skill).

Quick Reference

Find existing patterns:

# Find parameter in BobConfig
grep "PARAMETER_NAME" BobConfig.py

# Find in config_manager
grep -n "parameter_name" web/config_manager.py

# Find in HTML
grep -n "parameter_name" web/templates/config_*.html

Test after adding:

1. Restart web server
2. Navigate to config page
3. Verify field appears with correct default
4. Change value and save
5. Verify BobConfig.py updated correctly
6. Reload page and verify new value persists