Feature System

Feature System

How features work

Each feature is a self-contained module that provides specific functionality. Features follow a consistent structure and can be enabled/disabled independently.

The hello_world feature is intended as a template for new development.

Feature lifecycle

1. Registration: feature is listed in AVAILABLE_FEATURES in the root const.py.
2. Discovery: config flow discovers available features.
3. Activation: user enables/disables features via the integration options.
4. Creation: the framework imports the feature module and creates a feature instance.
5. Registration: feature platforms are registered with Home Assistant.
6. Operation: the feature runs independently (entities, services, automations, cards).

Available Features

• default - Always enabled, provides shared functionality
• humidity_control - Humidity-based ventilation with balance mode
• co2_control - CO2-based ventilation for air quality
• sensor_control - Central sensor mapping, resolution, and zone configuration
• hvac_fan_card - Advanced control interface card
• ramses_debugger - Debugging tools and traffic analysis
• hello_world - Developer template/example feature

Feature structure pattern

Feature metadata: FEATURE_DEFINITION

Each feature exposes a FEATURE_DEFINITION dict in features/<feature_id>/const.py. This is the single source of truth for feature metadata consumed by the framework.

The feature registry reads FEATURE_DEFINITION to register, among other things:

• entity configs (per platform)
• device-to-entity mappings
• WebSocket command metadata
• card metadata

Avoid adding parallel const structures (for example: FEATURE_WEB_CONFIGS, <FEATURE>_CONFIG, <FEATURE>_CARD_CONFIG).

Feature components

Each feature has a predictable structure. Some parts are optional depending on what the feature needs.

Required:

• __init__.py feature factory functions
• const.py feature constants and feature definition

Optional:

• automation.py Python automation logic (no YAML automation rules)
• services.py service implementations
• entities.py feature entity orchestration/helpers
• config.py feature-specific configuration manager
• platforms/ platform implementations for Home Assistant entities
• www/ JavaScript Lovelace cards and editors
• websocket_commands.py WebSocket command handlers

Adding a new feature

The hello_world feature can be used as a template.

High-level steps:

1. Copy custom_components/ramses_extras/features/hello_world/ to custom_components/ramses_extras/features/<your_feature_id>/.
2. Register the feature in AVAILABLE_FEATURES in the root const.py.
3. Add an options-flow step in config_flow.py (typically a method named async_step_feature_<your_feature_id>()).
4. Restart Home Assistant, enable the feature in the options flow, and verify:
   • entities are created
   • services work
   • cards load (if applicable)
   • logs look clean

Back to: Home Prev: System Architecture Next: Framework Foundation