From 68ab038d0fc85be37484808ccb7edb5a0bd75bda Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tinker=20S=C3=B6der?= Date: Sun, 25 Oct 2026 20:38:37 +0000 Subject: [PATCH 1/2] feat(import): add RAMSES RF / Ramses Extras device import New toolbar "RAMSES" modal that places evohome / RAMSES-II devices as markers: - live: Ramses Extras ramses_extras/floorplan_helper/get_topology over the HA WebSocket, falling back to the HA device/entity/area/floor registries filtered to ramses_cc (token and dashboard-card mode) - offline: paste/load a topology result, a floorplan_seed_studio response or studio project (merged, rooms included, scaled to the canvas), or any text with device ids (known_list, schema, packet log) - placement into the room mapped to the device's HA area (room areaId or name), else a staging row on the floor matching the area's HA floor; idempotent, one undo step - class icons + group colours, optional labels, extra entities and state rules (offline, battery low, window open, heat demand) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01WYxXqbVSPa3Zy3hXS7FyH3 --- CHANGELOG.md | 10 + README.md | 4 + USER_GUIDE.md | 32 ++ src/App.tsx | 5 +- src/ha/client.ts | 6 + src/ha/hassBridge.ts | 3 + src/panels/Toolbar.tsx | 6 +- src/ramses/RamsesImportModal.tsx | 389 ++++++++++++++++++++++++ src/ramses/fetch.ts | 77 +++++ src/ramses/plan.ts | 326 ++++++++++++++++++++ src/ramses/ramses.test.ts | 309 +++++++++++++++++++ src/ramses/topology.ts | 506 +++++++++++++++++++++++++++++++ src/styles.css | 24 ++ src/ui/HelpModal.tsx | 11 + 14 files changed, 1706 insertions(+), 2 deletions(-) create mode 100644 src/ramses/RamsesImportModal.tsx create mode 100644 src/ramses/fetch.ts create mode 100644 src/ramses/plan.ts create mode 100644 src/ramses/ramses.test.ts create mode 100644 src/ramses/topology.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index 9331957..9b77603 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added +- **RAMSES RF / Ramses Extras import** (toolbar → **RAMSES**): adds evohome / RAMSES-II + devices as markers. Reads live from Ramses Extras' + `ramses_extras/floorplan_helper/get_topology` WebSocket command, falling back to the HA + device/entity registries filtered to `ramses_cc` when Extras isn't installed. Offline it accepts a + pasted/loaded topology, a `floorplan_seed_studio` response or studio project (merged into the + current project, rooms included, scaled to the canvas), or any text with device ids + (`known_list`, schema, packet log). Devices land in the room mapped to their HA area (room + `areaId` or name), otherwise in a staging row on the floor matching the area's HA floor; class + icons, group colours, optional extra entities and state rules (offline, battery low, window + open, heat demand). Idempotent and one undo step. Works in both token and dashboard-card mode. - **Inline SVG delivery for ha-floorplan (no file copy)**: the export can now embed the whole floorplan SVG straight into the card as a `data:` URI (`config.image: { location: data:image/svg+xml…, cache: true }`), so there are diff --git a/README.md b/README.md index 2827a0c..15d9108 100644 --- a/README.md +++ b/README.md @@ -75,6 +75,10 @@ no HACS? The standalone build below still works. pulls the entity + area registries and subscribes to live states; "Test connection" button with clear CORS / mixed-content guidance. Token stays in your browser and is only ever sent to your own HA. +- **RAMSES RF / Ramses Extras import** — pull evohome zones, TRVs, thermostats, ventilation units, + CO₂ sensors and remotes straight from HA (Ramses Extras' floorplan helper, or plain `ramses_cc`), + or paste a topology / `floorplan_seed_studio` result / `known_list`. Devices auto-place into the + room mapped to their HA area, with class icons and ready-made state rules. - **Persistence** — named projects in IndexedDB with autosave; JSON export/import for portable backups; undo/redo history. - **Export** — ha-floorplan (SVG + `custom:floorplan-card` YAML + stylesheet), Picture diff --git a/USER_GUIDE.md b/USER_GUIDE.md index f38c54f..99d0141 100644 --- a/USER_GUIDE.md +++ b/USER_GUIDE.md @@ -81,6 +81,38 @@ HA instance. Click **Disconnect** to wipe it and return to demo mode. - Toggle **Preview** in the top bar to see your rules driven by live states (or the demo set). Toggle back to **Edit** to keep working. +### Import RAMSES RF / Ramses Extras devices + +For evohome / RAMSES-II systems run through [Ramses RF](https://github.com/ramses-rf/ramses_cc) +(`ramses_cc`) and, optionally, [Ramses Extras](https://github.com/wimpie70/ramses_extras): + +1. Draw a room for every space and set its **HA area** in the Inspector (or give the room the same + name as the HA area). This is how devices find their room. +2. Click **RAMSES** in the toolbar. +3. **Read RAMSES devices** (needs the Home Assistant link — token or dashboard-card mode): + - with **Ramses Extras** installed it calls `ramses_extras/floorplan_helper/get_topology`, which + already resolves zones, parent links, display names and each device's primary entity; + - without Extras it rebuilds the same list from the HA device/entity/area/floor registries, + filtered to `ramses_cc`. +4. Or **paste / load** offline data: + - a saved `get_topology` result (raw or wrapped in the WebSocket `result`), + - the response of the Extras service `ramses_extras.floorplan_seed_studio` (or any studio project + JSON) — its markers and missing rooms are **merged** into the current project, scaled to this + canvas, + - a ramses_cc `known_list`, a ramses_rf schema or even a packet log — every device id + (`04:123456`, zones `01:123456_02`) is matched to your HA entities. +5. Review the table: tick devices (gateway is off by default), choose labels, extra entities + (temperature, heat demand, CO₂…), ready-made **state rules** (offline grey, battery-low blink, + window-open icon, heat-demand gradient) and marker size. Each row shows where the device goes: + *room*, *staging row* (bottom edge of the floor matching the area's HA floor, else the active + floor) or *already on plan*. +6. **Add markers**. The whole import is one undo step, and running it again only adds devices that + aren't on the plan yet. + +Icons follow the device class: zone `home-thermometer`, TRV `radiator`, controller `thermostat`, +FAN `fan`, remote `remote`, CO₂ `molecule-co2`, relay `pipe-valve`, gateway `router-wireless`… +Heating devices are orange, ventilation blue. + ### Saving - Everything **autosaves** to your browser. Use **Projects** to create/open/delete projects, **Export current as JSON** for a backup, or **Import JSON…** to restore one. diff --git a/src/App.tsx b/src/App.tsx index 987d483..6449131 100644 --- a/src/App.tsx +++ b/src/App.tsx @@ -11,10 +11,11 @@ import { HelpModal } from './ui/HelpModal'; import { ConnectModal } from './ha/ConnectModal'; import { ProjectsModal } from './persist/ProjectsModal'; import { ExportModal } from './export/ExportModal'; +import { RamsesImportModal } from './ramses/RamsesImportModal'; import { useAutosave } from './persist/useAutosave'; import { subscribeHass, hassToSource, getHass, HassLike } from './ha/hassBridge'; -type ModalId = null | 'help' | 'connect' | 'projects' | 'export'; +type ModalId = null | 'help' | 'connect' | 'projects' | 'export' | 'ramses'; export default function App() { const [modal, setModal] = useState(null); @@ -97,6 +98,7 @@ export default function App() { onOpenExport={() => setModal('export')} onOpenProjects={() => setModal('projects')} onOpenConnect={() => setModal('connect')} + onOpenRamses={() => setModal('ramses')} onOpenHelp={() => setModal('help')} />
@@ -121,6 +123,7 @@ export default function App() { {modal === 'connect' && setModal(null)} />} {modal === 'projects' && setModal(null)} />} {modal === 'export' && setModal(null)} />} + {modal === 'ramses' && setModal(null)} />}
); } diff --git a/src/ha/client.ts b/src/ha/client.ts index a952adc..ff146aa 100644 --- a/src/ha/client.ts +++ b/src/ha/client.ts @@ -85,6 +85,12 @@ export class HaClient { }); } + /** Raw WebSocket command (registries, integration-specific commands like Ramses Extras). */ + async sendWS(msg: Record): Promise { + if (!this.conn) throw new Error('Not connected'); + return this.conn.sendMessagePromise(msg as { type: string }); + } + /** Call a service on the connected instance (used by preview tap actions). */ async callService(domain: string, service: string, data: Record): Promise { if (!this.conn) throw new Error('Not connected'); diff --git a/src/ha/hassBridge.ts b/src/ha/hassBridge.ts index 829e6dd..58de790 100644 --- a/src/ha/hassBridge.ts +++ b/src/ha/hassBridge.ts @@ -26,6 +26,9 @@ export interface HassLike { // degrade gracefully to state attributes when they're missing. entities?: Record; areas?: Record; + /** Lovelace's WebSocket helper — used for registry / integration commands. */ + callWS?: (msg: Record) => Promise; + connection?: { sendMessagePromise: (msg: Record) => Promise }; callService?: ( domain: string, service: string, diff --git a/src/panels/Toolbar.tsx b/src/panels/Toolbar.tsx index 9ada3e4..38b39a5 100644 --- a/src/panels/Toolbar.tsx +++ b/src/panels/Toolbar.tsx @@ -9,10 +9,11 @@ const TOOLS: { id: ToolId; label: string; key: string }[] = [ { id: 'window', label: 'Window', key: '' }, ]; -export function Toolbar({ onOpenExport, onOpenProjects, onOpenConnect, onOpenHelp }: { +export function Toolbar({ onOpenExport, onOpenProjects, onOpenConnect, onOpenRamses, onOpenHelp }: { onOpenExport: () => void; onOpenProjects: () => void; onOpenConnect: () => void; + onOpenRamses: () => void; onOpenHelp: () => void; }) { const tool = useStore((s) => s.tool); @@ -80,6 +81,9 @@ export function Toolbar({ onOpenExport, onOpenProjects, onOpenConnect, onOpenHel + diff --git a/src/ramses/RamsesImportModal.tsx b/src/ramses/RamsesImportModal.tsx new file mode 100644 index 0000000..9f29770 --- /dev/null +++ b/src/ramses/RamsesImportModal.tsx @@ -0,0 +1,389 @@ +import { useMemo, useRef, useState } from 'react'; +import { useStore } from '../state/store'; +import { Modal } from '../ui/Modal'; +import { iconPath } from '../ui/icons'; +import type { Project } from '../model/schema'; +import { EXTRAS_TOPOLOGY_WS, fetchRamsesTopology, liveWsCaller } from './fetch'; +import { + CLASS_LABEL, + GROUP_COLOR, + iconForClass, + parseRamsesInput, + RamsesTopology, + topologyFromIds, +} from './topology'; +import { + applyMerge, + applyPlan, + defaultSelection, + planProjectMerge, + planRamsesImport, + RowStatus, +} from './plan'; + +type Msg = { kind: 'ok' | 'err' | 'info'; text: string } | null; + +const STATUS_TEXT: Record = { + room: 'room', + staging: 'staging row', + exists: 'already on plan', + 'no-entities': 'no entities', + off: 'skipped', +}; + +const SOURCE_TEXT: Record = { + ramses_extras: 'Ramses Extras floorplan helper', + ramses_cc: 'ramses_cc device registry', + device_ids: 'device ids matched to HA entities', +}; + +export function RamsesImportModal({ onClose }: { onClose: () => void }) { + const project = useStore((s) => s.project); + const entities = useStore((s) => s.entities); + const usingDemo = useStore((s) => s.usingDemo); + useStore((s) => s.conn); // re-render when the HA link changes + const call = liveWsCaller(); + + const [text, setText] = useState(''); + const [busy, setBusy] = useState(false); + const [msg, setMsg] = useState(null); + const [topo, setTopo] = useState(null); + const [incoming, setIncoming] = useState(null); + const [selected, setSelected] = useState>(new Set()); + const [markerSize, setMarkerSize] = useState(32); + const [labels, setLabels] = useState(true); + const [extraEntities, setExtraEntities] = useState(true); + const [stateRules, setStateRules] = useState(true); + const [allFloors, setAllFloors] = useState(true); + const [includeRooms, setIncludeRooms] = useState(true); + const fileRef = useRef(null); + + function loadTopology(t: RamsesTopology, note?: string) { + setTopo(t); + setIncoming(null); + setSelected(defaultSelection(useStore.getState().project, t)); + setMsg({ + kind: 'info', + text: `${t.devices.length} RAMSES devices from the ${SOURCE_TEXT[t.source]}.${note ? ' ' + note : ''}`, + }); + } + + async function fetchLive() { + if (!call) return; + setBusy(true); + setMsg(null); + try { + const { topology, note } = await fetchRamsesTopology(call); + loadTopology(topology, note); + } catch (e) { + setMsg({ kind: 'err', text: (e as Error).message || String(e) }); + } finally { + setBusy(false); + } + } + + function parse(src: string) { + const r = parseRamsesInput(src); + switch (r.kind) { + case 'topology': + return loadTopology(r.topology); + case 'project': + setTopo(null); + setIncoming(r.project); + return setMsg({ + kind: 'info', + text: `Studio project "${r.project.name ?? 'seeded'}" with ${r.project.floors.length} floor(s) — its markers can be merged into this project.`, + }); + case 'ids': { + const t = topologyFromIds(r.ids, entities); + const matched = t.devices.filter((d) => d.entities.length).length; + return loadTopology( + t, + usingDemo + ? 'Connect to Home Assistant first — device ids are matched against your real entity list.' + : `${matched} matched to HA entities by id.`, + ); + } + default: + setMsg({ kind: 'err', text: r.error }); + } + } + + async function loadFile(file?: File | null) { + if (!file) return; + const t = await file.text(); + setText(t); + parse(t); + } + + const plan = useMemo( + () => + topo + ? planRamsesImport(project, topo, project.activeFloorId, { + selected, + markerSize, + labels, + extraEntities, + stateRules, + allFloors, + }) + : null, + [project, topo, selected, markerSize, labels, extraEntities, stateRules, allFloors], + ); + + const merge = useMemo( + () => (incoming ? planProjectMerge(project, incoming, project.activeFloorId, { includeRooms }) : null), + [project, incoming, includeRooms], + ); + + const counts = useMemo(() => { + const c = { room: 0, staging: 0, exists: 0, unmatchedAreas: new Set() }; + for (const r of plan?.rows ?? []) { + if (r.status === 'room') c.room++; + if (r.status === 'staging') { + c.staging++; + if (r.device.area_name || r.device.area_id) c.unmatchedAreas.add(r.device.area_name || r.device.area_id!); + } + if (r.status === 'exists') c.exists++; + } + return c; + }, [plan]); + + function toggle(id: string) { + setSelected((s) => { + const n = new Set(s); + n.has(id) ? n.delete(id) : n.add(id); + return n; + }); + } + + function selectWhere(pred: (group: string) => boolean) { + if (!topo) return; + setSelected( + new Set( + topo.devices.filter((d) => d.primary_entity && d.entities.length && pred(d.group)).map((d) => d.device_id), + ), + ); + } + + function finish(ids: string[], text: string) { + const st = useStore.getState(); + st.select(ids); + st.setTool('select'); + setMsg({ kind: 'ok', text }); + } + + function importDevices() { + if (!plan || plan.adds.length === 0) return; + let ids: string[] = []; + useStore.getState().commit((p) => { + ids = applyPlan(p, plan); + }); + const parts = [`Added ${ids.length} marker${ids.length === 1 ? '' : 's'}`]; + if (counts.room) parts.push(`${counts.room} placed in matching rooms`); + if (counts.staging) parts.push(`${counts.staging} parked along the bottom edge — drag them into place`); + finish(ids, parts.join(' · ') + '. Ctrl+Z undoes the whole import.'); + } + + function importMerge() { + if (!merge) return; + let ids: string[] = []; + useStore.getState().commit((p) => { + ids = applyMerge(p, merge); + }); + const rooms = merge.reduce((n, m) => n + m.rooms.length, 0); + finish(ids, `Merged ${ids.length} markers${rooms ? ` and ${rooms} rooms` : ''}. Ctrl+Z undoes it.`); + } + + const mergeMarkers = merge?.reduce((n, m) => n + m.markers.length, 0) ?? 0; + const mergeRooms = merge?.reduce((n, m) => n + m.rooms.length, 0) ?? 0; + + return ( + +

+ Drop your evohome / RAMSES-II devices onto the plan as markers — zones, radiator valves, thermostats, + ventilation units, CO₂ sensors and remotes. Devices whose HA area matches a room (the room's{' '} + HA area or its name) land inside that room; the rest wait in a staging row at the bottom of + the floor. +

+ +
+
+
From Home Assistant
+ +
+ {call + ? 'Uses Ramses Extras when installed, otherwise the ramses_cc integration directly.' + : 'Connect to Home Assistant first (top-right HA button).'} +
+
+
+
Paste or load
+