Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 15 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

### Added

- **Plugin API** (`window.floorplanStudio`): third-party integrations can register their own
device sources, toolbar actions and style defaults via `registerPlugin({id, apiVersion, provides})`.
The manifest is data plus functions the editor calls — no DOM refs are handed out, unknown
`provides` keys are ignored so plugins and the editor version independently. Capability slots:
`deviceSources` (shown in the **Devices** modal: `fetch(ws)` for live import, `parse(text)` for
offline input), `actions` (toolbar items that emit a documented `floorplan-studio:action`
CustomEvent with `{pluginId, actionId, projectId, floorId, selection}`), `iconMap`,
`markerDefaults`, `stateRulePresets` (role-bound rules appended to imported markers) and `css`
(injected once, into the card's shadow root in HACS mode). Also new: `importProject()` merging a
project fragment in one undo step, `projects.*` (list/get/save/remove/open) replacing direct
IndexedDB access, `callWS()` for the active HA link, and documented events
(`floorplan-studio:action`, `floorplan-studio:project-imported`,
`floorplan-studio:plugins-changed`). See USER_GUIDE → *Plugin API for integrations*; the bundled
RAMSES source registers through the same public API as the reference implementation.
- **Import a floorplan card already in Home Assistant** (toolbar → **Import card**): scans every
Lovelace dashboard over the WebSocket (or takes pasted card / view / dashboard YAML) for
`custom:floorplan-card` and `picture-elements` cards and imports one as a new project or a new
Expand All @@ -19,7 +33,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
area / name; the remaining drawing becomes the background with converted elements stripped.
Studio's own exports round-trip icons, colours, labels and state rules.
- Room inspector keeps an imported HA area visible even when it isn't in the entity list.
- **RAMSES RF / Ramses Extras import** (toolbar → **RAMSES**): adds evohome / RAMSES-II
- **RAMSES RF / Ramses Extras import** (toolbar → **Devices** → *RAMSES RF / Ramses Extras*): 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
Expand Down
10 changes: 6 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,10 +79,12 @@ no HACS? The standalone build below still works.
picture-elements cards and bring them back as an editable floor: bound SVG elements → markers at
their real positions, `area.*` / `room_*` shapes → rooms, the rest of the drawing → background.
Round-trips Studio's own exports and Ramses Extras' generated floorplans.
- **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.
- **Integration device import** — pull devices straight from HA via plugin-provided
sources, or paste whatever a source recognises offline. Devices auto-place into the
room mapped to their HA area, with class icons and ready-made state rules. Integrations
ship their own source (e.g. Ramses Extras registers RAMSES devices via
`ramses_extras/floorplan_helper`); a bundled **HA registry** source serves as the reference
example.
- **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
Expand Down
109 changes: 91 additions & 18 deletions USER_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -110,32 +110,45 @@ What you get:
- **picture-elements**: the image becomes the background (canvas = image size) and each positioned
entity element a marker (`state-label` → live label, conditional elements → marker visibility).

### Import RAMSES RF / Ramses Extras devices
### Import devices (registered integrations)

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):
The **Devices** toolbar button opens the generic device importer. The sources it lists come from
integrations registered through the [plugin API](#plugin-api-for-integrations) — Floorplan Studio
ships a bundled RAMSES RF source described below; other integrations (yours?) can register their own.

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
2. Click **Devices** in the toolbar and pick a source (needs the Home Assistant link — token or
dashboard-card mode).
3. Or **paste / load** whatever a source recognises offline — the modal tries each registered
source's parser, and a raw studio project JSON merges without one.

**Bundled source: MQTT** (`src/examples/ha-devices.ts`) — lists every device in the HA registry, grouped by integration
via the HA entity registry. It exists as the **reference implementation** for the plugin
API, not as an integration play: real integrations ship their own provider as a Lovelace
resource (see below).

**RAMSES RF / Ramses Extras** — for evohome / RAMSES-II systems run through
[Ramses RF](https://github.com/ramses-rf/ramses_cc) (`ramses_cc`),
[Ramses Extras](https://github.com/wimpie70/ramses_extras) ships its own provider
(`ramses-studio-provider.js`, auto-registered by the integration):

- **RAMSES RF / Ramses Extras** (live) — 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` (reading both `via_device_id`
and the HA 2026.9+ `parent_device_id` for parent links).
- Offline **paste / load**: 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 — or a ramses_cc `known_list`, ramses_rf schema or packet log: every device
id (`04:123456`, zones `01:123456_02`) is matched to your HA entities.
4. Review the table: tick devices (gateways are 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
5. **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`,
Expand Down Expand Up @@ -197,3 +210,63 @@ After adding the card, toggle one of your lights from the map and confirm the ma
colour follows the entity state, and that any sensor markers show their live value. If a
marker sits slightly off, nudge it in the editor (arrow keys) and re-export — because the
export is embedded, that's just Copy YAML → replace the card contents.

---

## Plugin API for integrations

Floorplan Studio exposes `window.floorplanStudio` so third-party integrations can register their own
**device sources, actions and style defaults** — no integration-specific code needs to live
in this repository. The bundled HA-registry source (`src/examples/ha-devices.ts`) registers through exactly
this public API and doubles as the reference implementation.

```ts
window.floorplanStudio.registerPlugin({
id: 'ramses', // unique; re-registering replaces (external may supersede bundled)
apiVersion: 1,
provides: {
deviceSources: [{
id: 'ramses',
title: 'RAMSES RF / Ramses Extras', // label in the Devices modal
description: 'evohome / RAMSES-II devices',
fetch: async (ws, ctx) => ({ // live: called with the active HA WebSocket
topology: { source: 'ramses_extras', devices: [...], areas: {}, floors: {} },
note: 'optional extra line under the count',
}),
parse: (text, ctx) => ({ kind: 'topology' | 'project' | 'error' | 'nomatch', ... }),
}],
actions: [{
id: 'ramses.seed-devices', label: 'Add devices', icon: 'devices', location: 'toolbar',
}],
iconMap: { FAN: 'fan', TRV: 'radiator' }, // class token → mdi icon fallback
markerDefaults: { size: 40 }, // merged: plugin < user opts < device hints
stateRulePresets: [ // appended to imported markers, role-bound
{ entityRole: 'battery', mode: 'stringMatch', match: 'on', color: '#ef4444', animation: 'blink' },
],
css: '/local/my_integration/floorplan.css', // injected once (card mode: shadow root)
},
});
```

- **The manifest is data + functions the editor calls** — no DOM refs, no component internals,
the editor keeps lifecycle control. Unknown `provides` keys are ignored: plugins and the editor
version independently (`apiVersion`).
- **DeviceTopology** is the neutral model sources return: `devices[]` with `device_id`,
`device_class`/`group` (free-form display/grouping tokens), `area_id`, `primary_entity`,
`entities[]` (`{entity_id, domain, role}`), plus optional `icon`/`color`/`kind`/`suggested`
presentation hints, `actions`/`style`/`visibility` passthrough (per-gesture overrides, e.g. a
FAN's double-tap opening a custom card — users can still edit per-marker afterwards), and
`parent` for topology-aware integrations.
- **Events** need no registry — just `addEventListener` on `window`:
- `floorplan-studio:action` — a plugin action was clicked.
`detail: {pluginId, actionId, projectId, floorId, selection: string[]}`
- `floorplan-studio:project-imported` — `detail: {pluginId?, mode, markers, rooms}`
- `floorplan-studio:plugins-changed` — `detail: {plugins: string[]}`
- **`floorplanStudio.importProject(json, {mode})`** — merge a studio project/fragment into the open
project in one undo step (`'merge'`, default; floors pair by name, scaled to the canvas) or
`'replace'` it. This replaces writing to the editor's IndexedDB directly.
- **`floorplanStudio.projects`** — `active()`, `list()`, `get(id)`, `save(p)`, `remove(id)`,
`open(id)` — the supported way to read/write stored projects.
- **`floorplanStudio.callWS(msg)`** — call the active Home Assistant WebSocket (throws when not
connected); also `floorplanStudio.registry.*` for introspection and `subscribe(cb)` to be notified
when the plugin set changes.
35 changes: 27 additions & 8 deletions src/App.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -4,23 +4,35 @@ import { loadImageFile } from './ui/imageLoad';
import { useKeyboard } from './ui/useKeyboard';
import { Toolbar } from './panels/Toolbar';
import { EntityBrowser } from './panels/EntityBrowser';
import { DevicePanel } from './panels/DevicePanel';
import { Inspector } from './panels/Inspector';
import { LayerPanel } from './panels/LayerPanel';
import { CanvasSvg } from './canvas/CanvasSvg';
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 { DeviceImportModal } from './import/DeviceImportModal';
import { HaImportModal } from './haimport/HaImportModal';
import { useAutosave } from './persist/useAutosave';
import { subscribeHass, hassToSource, getHass, HassLike } from './ha/hassBridge';

type ModalId = null | 'help' | 'connect' | 'projects' | 'export' | 'ramses' | 'haimport';
type ModalId = null | 'help' | 'connect' | 'projects' | 'export' | 'import' | 'haimport';

function LeftTab({ id, label }: { id: 'entities' | 'devices' | 'layers'; label: string }) {
const active = useStore((s) => s.leftTab === id);
const setLeftTab = useStore((s) => s.setLeftTab);
return (
<button className={active ? 'active' : ''} onClick={() => setLeftTab(id)}>
{label}
</button>
);
}

export default function App() {
const [modal, setModal] = useState<ModalId>(null);
const mode = useStore((s) => s.mode);
const leftTab = useStore((s) => s.leftTab);
useKeyboard();
useAutosave();

Expand Down Expand Up @@ -99,15 +111,20 @@ export default function App() {
onOpenExport={() => setModal('export')}
onOpenProjects={() => setModal('projects')}
onOpenConnect={() => setModal('connect')}
onOpenRamses={() => setModal('ramses')}
onOpenHaImport={() => setModal('haimport')}
onOpenImport={() => useStore.getState().setLeftTab('devices')}
onOpenHelp={() => setModal('help')}
/>
<div className="fp-body">
{mode === 'edit' && (
<aside className="fp-left">
<EntityBrowser />
<LayerPanel />
<div className="fp-left-tabs">
<LeftTab id="entities" label="Entities" />
<LeftTab id="devices" label="Devices" />
<LeftTab id="layers" label="Layers" />
</div>
{leftTab === 'entities' && <EntityBrowser />}
{leftTab === 'devices' && <DevicePanel onOpenImport={() => setModal('import')} />}
{leftTab === 'layers' && <LayerPanel />}
</aside>
)}
<main className="fp-center">
Expand All @@ -123,9 +140,11 @@ export default function App() {

{modal === 'help' && <HelpModal onClose={() => setModal(null)} />}
{modal === 'connect' && <ConnectModal onClose={() => setModal(null)} />}
{modal === 'projects' && <ProjectsModal onClose={() => setModal(null)} />}
{modal === 'projects' && (
<ProjectsModal onClose={() => setModal(null)} onImportCard={() => setModal('haimport')} />
)}
{modal === 'export' && <ExportModal onClose={() => setModal(null)} />}
{modal === 'ramses' && <RamsesImportModal onClose={() => setModal(null)} />}
{modal === 'import' && <DeviceImportModal onClose={() => setModal(null)} />}
{modal === 'haimport' && <HaImportModal onClose={() => setModal(null)} />}
</div>
);
Expand Down
31 changes: 22 additions & 9 deletions src/canvas/MarkersLayer.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,11 @@ import {
markerIcon,
markerVisible,
ruleAnimation,
ruleSpinDuration,
stateLabel,
} from '../state/resolve';
import { iconPath } from '../ui/icons';
import { markerGestureHandlers, GestureTimers } from './actions';
import { snapPoint } from './geometry';

interface Props {
Expand Down Expand Up @@ -46,13 +48,17 @@ function MarkerNode({
moved: boolean;
} | null>(null);

const gestureTimers = useRef<GestureTimers>({}).current;
const preview = mode === 'preview';
if (preview && !markerVisible(m, states)) return null;
// Preview = live-card semantics: clicks fire the marker's gesture actions.
const gesture = preview ? markerGestureHandlers(m, gestureTimers) : null;

const locked = floor.layers.entities.locked;
const color = preview ? markerColor(m, states) : m.style.color;
const icon = preview ? markerIcon(m, states) : m.style.icon;
const anim = preview ? ruleAnimation(m.stateRules, states, m.entities[0]) : null;
const spinDur = preview && anim === 'spin' ? ruleSpinDuration(m.stateRules, states, m.entities[0]) : undefined;
const size = m.style.size;

function onPointerDown(e: React.PointerEvent) {
Expand Down Expand Up @@ -121,10 +127,12 @@ function MarkerNode({
<g
transform={`translate(${m.x} ${m.y})`}
style={{ cursor: mode === 'edit' && !locked ? 'move' : 'pointer' }}
onPointerDown={onPointerDown}
onPointerMove={onPointerMove}
onPointerUp={onPointerUp}
className={anim ? `fp-anim-${anim}` : undefined}
onPointerDown={gesture?.onPointerDown ?? onPointerDown}
onPointerMove={gesture?.onPointerMove ?? onPointerMove}
onPointerUp={gesture?.onPointerUp ?? onPointerUp}
onClick={gesture?.onClick}
onDoubleClick={gesture?.onDoubleClick}
className={anim && anim !== 'spin' ? `fp-anim-${anim}` : undefined}
>
{/* selection ring */}
{selected && mode === 'edit' && (
Expand All @@ -136,11 +144,16 @@ function MarkerNode({
{m.style.type === 'icon' && (
<>
<circle r={size * 0.5} fill="rgba(20,24,33,0.55)" />
<path
d={iconPath(icon)}
fill={color}
transform={`translate(${-size * 0.35} ${-size * 0.35}) scale(${(size * 0.7) / 24})`}
/>
<g
className={anim === 'spin' ? 'fp-anim-spin' : undefined}
style={spinDur ? ({ '--fp-spin-duration': spinDur } as React.CSSProperties) : undefined}
>
<path
d={iconPath(icon)}
fill={color}
transform={`translate(${-size * 0.35} ${-size * 0.35}) scale(${(size * 0.7) / 24})`}
/>
</g>
</>
)}

Expand Down
Loading