Floorplan Helper

Floorplan Helper

A live, graphical view of your RAMSES system on a floorplan — without hand-writing ha-floorplan rules.

Overview

Floorplan Helper discovers your RAMSES topology (FAN, zones/TRVs, controller, DHW, remotes, sensors, gateways) and generates everything the community ha-floorplan card needs: the SVG, the stylesheet, and the full managed rules: block — status colors, fan spin animation, state captions, tap/hold/double-tap gestures, zone highlighting, pan/zoom, and an in-plan toolbar.

floorplan-studio is the per-marker editor: what you draw and configure in studio is what the export emits. The studio project is the single source of truth — extras never keeps a second copy of per-marker settings that could conflict.

Page	For
Getting Started	From zero to a live floorplan on your dashboard
Editing & Updating	Day-to-day edits: markers, zones, gestures, re-export

How it works

ramses_cc topology + HA registries ──► device model (topology.py)
                                            │
                              studio project (latest.json) ── markers,
                                            │                 rooms, actions
                                            ▼
                              floorplan_export (the compiler)
                                            │
        ┌───────────────────────┬───────────┴──────────┬─────────────────┐
        ▼                       ▼                      ▼                 ▼
  merged SVG(s)           ramses-floorplan.css    managed rules:    card YAML
  (your drawing +         (rx-* status layer)   gestures + status   (paste once)
  markers + toolbar)                            + captions + zones

• You edit in studio — icon, color, label, state text on/off, tap/hold/double actions, position. It persists in the project.
• Export compiles — ramses_extras.floorplan_export reads the project + live topology and emits the card bundle. Re-run it after every change; it never loses studio edits.
• Extras adds what studio can't express — the rx-* status layer, combined multi-entity captions, zone sync across cards, the toolbar, and pan/zoom. These are generated and additive-only, so they can't conflict with studio-owned fields.

What a marker looks like

Markers render as badges: a colored disc (studio's marker color) with a light icon glyph, a thin ring for status/zone indication, and captions below:

• Ring — zone membership (tap a zone parent), heat demand (orange), valve open, window open (blue)
• Disc — offline grey + dashed ring; fan speed tints the disc green/orange/red
• Icon — spins proportionally to fan speed (rx-spin animation)
• Captions — name above, combined state text below (e.g. 35% / 20.1°, 402 ppm, 12.9° / 9.1°)

The studio field → output mapping

Studio field	Used for
marker.actions.tap/hold/double	Gesture actions — more-info, toggle, navigate, url, call-service (incl. YAML serviceData)
marker.entities + elementId	Rule binding / SVG element id
marker.style.icon	Marker glyph
marker.style.color	Badge disc color
marker.style.size	Marker size
marker.style.label	Name caption (wins over the generated slug)
marker.style.showState	State caption on/off
marker.ramsesZone (our key)	Zone config — areas + bound devices + color
marker.ramsesCaption (our key)	Caption spec — ["eid|suffix", …]; [] hides it
style.glyph/ring/opacity (our keys)	Glyph color, always-on ring, marker opacity (alpha ok)
project.ramsesDeviceViewUrl (our key)	Double-tap navigate target
room fill/opacity/stateRules	Room styling

Our custom keys are unknown to studio — which is the point. Studio round-trips unknown fields untouched through import, edit, and export, so they live safely inside the project.

Zones

A zone parent (FAN, controller) can be bound to the rooms it serves. Tapping its marker hatches the served rooms and rings the bound devices on every floorplan card — synced via a real HA event, so it works across browsers too.

• Tap → highlight the zone (a call-service to ramses_extras.floorplan_zone_toggle)
• Hold → more-info on the device
• Double-tap → the device view popup (ramses_extras.floorplan_device_view) or your own navigate

Zones are set with floorplan_set_device_zone and stored on the marker as ramsesZone — visible and editable in the project, not in a config menu.

Services

Service	Purpose
floorplan_export	Compile project + topology → bundle files + card YAML
floorplan_seed_studio	Emit a studio project with rooms + pre-placed markers
floorplan_store_project	Store a studio export as the canonical project
floorplan_sync_areas	Marker positions → HA area assignments (with dry_run)
floorplan_set_device_zone	Bind a device to served rooms/devices (writes the marker)
floorplan_set_icon	Icon override — writes marker.style.icon + option fallback
floorplan_set_element	Element binding / extra rules for non-marker elements
floorplan_assign_area	Device/zone → HA area override
floorplan_set_svg	Switch SVG mode, toolbar/tool URLs
floorplan_import	Paste floorplan YAML → element bindings + extra rules
floorplan_upload_svg	Write an SVG into the floorplan www dir
floorplan_zone_toggle	Zone highlight event bridge (called by taps, not you)
floorplan_device_view	Device-popup event bridge (called by double-taps)

There's also a button.floorplan_export entity for one-press regeneration.

Prerequisites

• ha-floorplan via HACS — we never ship floorplan.js; the export warns when the lovelace resource is missing.
• floorplan-studio via HACS — the editor. Technically optional (a generated elements SVG works without it) but it's where all per-marker editing happens. Back to: Home | Prev: HVAC Fan Card | Next: Getting Started