Hello World

Hello World (Developer Example)

A template feature demonstrating complete Ramses Extras architecture.

Purpose

The Hello World feature serves as a reference implementation for developers who want to create new features. It demonstrates all standard components of a Ramses Extras feature while keeping the code small and readable.

What It Demonstrates

Complete Feature Architecture

The Hello World feature shows all standard components:

• Automation logic – Python-based automation using framework base classes
• Configuration management – Integration with options flow and validation
• Entities – Sensor, switch, number, and binary_sensor implementations
• Services – Custom services for feature control
• Platform implementations – Device iteration and entity creation
• Lovelace card – Custom card with editor configuration
• WebSocket commands – Real-time communication with frontend

Best Practices

The template demonstrates these architectural best practices:

Single Source of Truth

• Define entity templates and metadata in features/<feature_id>/const.py via FEATURE_DEFINITION
• Avoid duplicating configuration structures

Prefer Framework Helpers

• Use framework.helpers.platform.PlatformSetup to avoid duplicating device iteration patterns
• Use framework.helpers.device.core.find_ramses_device() / get_device_type() for device filtering
• Use framework.helpers.entity.core.EntityHelpers to generate entity IDs from templates

Keep Entities Thin

• Feature entities should add feature-specific attributes/behavior
• Common state handling should live in framework base classes

Avoid Parallel Config Structures

• Do not introduce new ad-hoc *_CONFIGS / *_CARD_CONFIG registries
• Keep everything within FEATURE_DEFINITION

Usage for Developers

Creating a New Feature

1. Copy the hello_world folder:

cd /path/to/ramses_extras/custom_components/ramses_extras/features
cp -r hello_world your_new_feature

2. Rename files and update references:

• Replace hello_world with your feature name in filenames
• Update class names and imports
• Update the feature ID in const.py

3. Prune what you don't need:

• The template exercises every layer – remove unused components
• Keep only what your feature actually needs

4. Implement your feature logic:

• Add your automation logic in the automation module
• Configure entities as needed
• Add WebSocket commands if required

Development Workflow

1. Enable the feature in the options flow for testing
2. Use the template entities to verify setup
3. Gradually replace template logic with your feature logic
4. Remove unused components as you go

Configuration

The Hello World feature is configured through the standard Ramses Extras options flow:

1. Go to Settings → Integrations
2. Find Ramses Extras and click Configure
3. Enable Hello World for your devices
4. Configure feature-specific options

Entities Created

The feature creates these example entities (per device):

Entity	Type	Purpose
sensor.hello_world_{device_id}	Sensor	Example sensor entity
switch.hello_world_{device_id}	Switch	Example switch entity
number.hello_world_{device_id}	Number	Example number entity
binary_sensor.hello_world_{device_id}	Binary Sensor	Example binary sensor

Services

The feature provides these example services:

• hello_world.say_hello – Example service that logs a message
• hello_world.set_value – Example service that updates the number entity

WebSocket Commands

These commands are available for frontend communication:

• hello_world/get_status – Get current feature status
• hello_world/send_message – Send a message to the feature

Frontend Card

The feature includes a custom Lovelace card:

type: custom:hello-world-card
entity: sensor.hello_world_32_153289

The card demonstrates:

• Real-time updates via WebSocket
• Configuration editor
• Theme adaptation
• Entity state display

Learning Path

Use Hello World to learn:

1. Feature Structure – How files are organized
2. Entity Creation – How to create and manage entities
3. Automation – How to implement automation logic
4. Configuration – How to handle user configuration
5. Frontend Integration – How to create custom cards

Related Documentation

• Feature System – Architecture overview
• Framework Foundation – Helper classes and utilities
• Entity Management – Entity creation and management
• Frontend Architecture – Card development guide

Back to: Home | Prev: Default Feature | Next: HVAC Fan Card