Development Guide

Development Guide

You are welcome to contribute to this integration. If you are missing support for a device, or have a nice card that you like to share, please do.

Also see the repository "Contributing" information for environment setup.

Coding standards and conventions

File responsibilities

• Root platform files: thin Home Assistant integration wrappers that forward to feature implementations
• Feature files: feature-specific business logic and entity implementations
• Framework files: reusable utilities and base classes
• Frontend files: JavaScript/HTML assets for UI components

Naming conventions

• Feature names: snake_case (e.g. humidity_control)
• Entity classes: PascalCase (often feature-prefixed)
• Helper functions: snake_case
• Constants: UPPER_SNAKE_CASE

Import patterns

# Feature imports (relative)
from ...automation import HumidityAutomationManager

# Framework imports (absolute)
from custom_components.ramses_extras.framework.helpers.automation import ExtrasBaseAutomation
from custom_components.ramses_extras.framework.helpers.entity import EntityHelpers

# Root imports (absolute)
from custom_components.ramses_extras.const import DOMAIN
from homeassistant.config_entries import ConfigEntry

Framework components should generally use absolute imports from features to avoid module resolution edge cases.

Development workflow

Framework-first development

When developing new features, follow this framework-first approach:

1. Step 1: Start with framework components for configuration, entities, and services
2. Step 2: Use platform entity base classes for HA integration
3. Step 3: Leverage brand customization and service frameworks
4. Step 4: Implement feature-specific business logic only

Feature development with framework

Start from the hello_world feature as a reference implementation; it exercises every layer (entities, services, automations, UI) so it's the recommended template before pruning what you don't need.

# Example: New feature using full framework
def create_my_feature(hass: HomeAssistant, config_entry: ConfigEntry) -> dict[str, Any]:
    """Create feature using framework patterns."""

    # Configuration management
    config = MyFeatureConfig(hass, config_entry, "my_feature", MyFeatureConfig.DEFAULT_CONFIG)

    # Simple entity management
    entity_manager = SimpleEntityManager(hass)

    # Service framework
    service_manager = MyFeatureServices(hass, config_entry)

    # Platform setup framework
    platform_setup = PlatformSetup(hass, config_entry)

    return {
        "config": config,
        "entity_manager": entity_manager,
        "service_manager": service_manager,
        "platform_setup": platform_setup,
        "platforms": {
            "sensor": MyFeatureSensor,  # Uses ExtrasSensorEntity
            "switch": MyFeatureSwitch,  # Uses ExtrasSwitchEntity
            "number": MyFeatureNumber,  # Uses ExtrasNumberEntity
        },
    }

Framework component integration

• Use ExtrasConfigManager for all configuration needs
• Inherit from platform entity classes (ExtrasSwitchEntity, etc.)
• Register services through ExtrasServiceManager
• Apply brand customizations through BrandCustomizerManager
• Use SimpleEntityManager for entity operations

Testing

• Use framework helpers for consistent testing patterns
• Test features independently using the framework foundation
• Follow HA testing standards and patterns
• Leverage framework validation and error handling

Documentation

• Document feature API and configuration options
• Update architecture guide for new patterns or components
• Provide examples of framework usage
• Include migration notes for legacy patterns

Testing structure

Tests are grouped by type:

tests/
├── managers/
├── helpers/
├── frontend/
├── config_flow/
├── startup/
└── test_registry.py

End-to-end testing on ha-sim

For integration testing against a running ha-sim container, use the automated test tool:

cd /home/willem/dev/ramses_extras
source ~/venvs/extras/bin/activate
python -m tools.ha_sim_test

This runs 449 checks across 73 recipes in ~6 minutes (100x simulator speed) and generates log + summary reports. See HA-Sim Test Tool for full details.

Back to: Home

Prev: Directory Structure Next: Debugging and Troubleshooting