System Architecture

System Architecture

High-level architecture

┌────────────────────────────────────────────────────────────┐
│                    Home Assistant                          │
├────────────────────────────────────────────────────────────┤
│  Ramses Extras Integration (Thin HA Wrapper)               │
├────────────────────────────────────────────────────────────┤
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐        │
│  │   Feature 1  │ │   Feature 2  │ │   Feature N  │        │
│  │ (Humidity)   │ │ (HVAC Card)  │ │   (Custom)   │        │
│  └──────────────┘ └──────────────┘ └──────────────┘        │
├────────────────────────────────────────────────────────────┤
│  Framework Foundation (Base Classes, Helpers, Managers)    │
├────────────────────────────────────────────────────────────┤
│  ramses_cc Integration (Device Communication)              │
└────────────────────────────────────────────────────────────┘

Core design principles

Feature-centric organization

• Each feature is self-contained (automation, services, entities, config, cards).
• Features are modular: enabling a feature does not require enabling all others.
• A default feature provides shared/common functionality.

Framework foundation

• Shared base classes for entities and automations.
• Reusable helpers for setup, config flows, registry operations, shared fan-control policy, and diagnostics.

Python-based automations (not YAML)

• Automations are implemented as Python classes.
• They listen to ramses_cc events and device state changes.
• FAN-related automations publish demand to the shared fan-speed arbiter instead of directly owning final fan state.

ramses_cc integration hooks

• Broker access for device communication.
• Event subscriptions (real-time message handling).
• Shared constants and schemas.

Home Assistant integration

• Standard HA platforms (sensor/switch/binary_sensor/number).
• Type-safe entity implementations.
• Shared diagnostics from the default feature for FAN devices.

Directory structure (overview)

At a high level, the repo is split into:

• custom_components/ramses_extras/ integration entry points and platform files
• custom_components/ramses_extras/features/ feature-centric modules
• custom_components/ramses_extras/framework/ reusable foundation

Integration flow (setup pipeline)

The main setup pipeline is orchestrated by the setup framework in custom_components/ramses_extras/framework/setup/.

Setup phases (summary)

• Early entry setup (async_setup_entry)

  • Initializes hass.data state
  • Watches the entity registry for new ramses_cc entities

• Main setup pipeline

  • Load feature definitions + import enabled feature platform modules
  • Discover devices and coordinate async_setup_platforms with ramses_cc
  • Setup WebSocket integration
  • Deploy Lovelace card assets + expose frontend config
  • Register services
  • Validate entities + cleanup orphaned devices
  • Create and start feature instances (automation lifecycle)

Configuration update flow

When options change, the integration reloads and:

• updates runtime state derived from config entry options
• refreshes frontend configuration
• re-evaluates device/feature selections and entity requirements

This allows a UI-driven workflow without relying on YAML automations.

YAML support (secondary method)

YAML is not the primary configuration method.

If present, YAML is only used as a secondary bootstrap mechanism to create an initial config entry. After that, the config entry (and its options) become authoritative.

Asset deployment strategy

Frontend card assets are deployed under versioned directories in /config/www/ramses_extras/v{version}/..., while the Lovelace bootstrap resource uses a stable path with a cache-busting query string:

• /local/ramses_extras/helpers/main.js?v=<version>

This keeps browser caching predictable without requiring users to update the resource URL on every release.

Device discovery strategy

Device discovery is coordinated with ramses_cc:

• Prefer direct broker/device access where possible.
• Fall back to entity-registry based extraction when needed.
• Emit/handle discovery signals so platform setup happens only when devices are ready for entity creation.

ramses_cc integration architecture

Ramses Extras depends on ramses_cc being available and ready.

• It will wait/retry if ramses_cc has not finished loading.
• Device discovery prefers direct broker access and falls back to registry-based extraction.

Schema as sole source of truth (Phase 4)

Since ramses_cc Phase 4 (config entry version 3), the schema is the sole source of truth for device topology and traits. The legacy known_list and enforce_known_list config entry options have been removed:

• enforce_known_list is always on — hardcoded in the coordinator
• known_list is derived at runtime from the schema via _derive_known_list_from_schema() — not stored in the config entry
• Device traits (_class, _alias, _faked, _bound, _scheme, _disabled, _owner) live as _-prefixed keys inside device entries in the schema
• Devices are added to the schema via the passive scan discovery flow (scan detects new devices, user accepts them in the ramses_cc UI) or by manual editing in the schema editor
• The v2→v3 config entry migration merges legacy known_list traits into the schema automatically and enables passive scan

The schema structure includes:

• main_tcs — the primary controller ID
• Per-device entries with _-prefixed traits and structural keys (zones, remotes, sensors, stored_hotwater, system)
• orphans_heat / orphans_hvac — lists of device IDs not yet placed in the topology
• _owner (root-level) — system owner name; devices with a different _owner are "foreign" (excluded from known_list, added to block_list)

ramses_extras reads the schema from ramses_cc's config entry options when needed (e.g., the device simulator's profile loader writes and clears it during test setup).

ramses_cc readiness and dependency management

Startup is dependency-aware:

• Ramses Extras expects ramses_cc to be loaded before doing full discovery.
• When ramses_cc is not ready yet, setup is delayed and retried.
• This prevents half-initialized features and missing device contexts.

Device binding requirement (FAN-related features)

For FAN-related features you typically need the Ramses RF bound REM mapping. See:

• Getting Started (Users)

Back to: Home Prev: FAN Configuration (Sensor Control) Next: Feature System