Drawing the plan

🇫🇷 Version française

Drawing the plan

What a plan is made of, how each part looks and which keys it writes. Furniture has its own page: Furniture.

• Coordinates
• Rooms · Outdoor areas · Sub-areas
• Walls · Boundaries and fences
• Openings: types, leaves and swing, shutters, contacts, bays
• Texts and info boxes
• Room labels, colours and legend
• Framing
• Layers and groups

Coordinates

Everything is in centimetres. x grows to the right, y grows downwards. A point is [x, y], a segment [x1, y1, x2, y2], a room outline a list of points. The editor writes these for you; you only need them to edit the YAML by hand.

Rooms

A room is a polygon with optional sensors. Tapping it opens its room view.

rooms:
  - name: Living room
    poly: [[0, 0], [500, 0], [500, 420], [0, 420]]
    label: [250, 210]                 # label position; no label without it
    temperature: sensor.living_room_temperature
    humidity: sensor.living_room_humidity
    area: living_room                 # Home Assistant area: devices, scenes, automations
    tap: sensor.living_room_temperature   # entity opened from the label in the room view

• Tint: the floor is coloured by temperature, from blue (17 °C and below) to red (28 °C and above); see Room labels, colours and legend. Without a temperature the floor stays neutral.

• Label: name, temperature (1 decimal) and humidity (0 decimals). The editor's Show label adds or removes label.

• Sensor attributes: temperature_attribute / humidity_attribute read an attribute instead of the state, for a weather or climate entity:

  rooms:
    - name: Terrace
      poly: [[0, 420], [500, 420], [500, 700], [0, 700]]
      label: [250, 560]
      outside: true
      temperature: weather.home
      temperature_attribute: temperature

• area links a Home Assistant area. The room view then lists its entities, scenes and automations, its Automatic buttons act on its lights and shutters, and the editor proposes its sensors. In the editor, Home Assistant area with Add the area's devices places one badge per main device.

• Room view: zoom: false disables it (the label still opens tap). auto_actions: false hides the automatic buttons, automations: false the linked automations, actions adds your own buttons, panels gives the room its own side panels. See Using the card › Room view.

• A room needs at least three valid points; otherwise it is ignored (and removed at the next save).

Editor: R (rectangle with its walls, then exact Width / Height), P (freeform), Add › Rooms › Home Assistant area or All my HA areas.

Outdoor areas

outside: true marks a terrace, a garden, a balcony, a carport: no temperature tint, not counted in the indoor temperature chip, a stronger night tint, sunlight from the sun's side, and the only place where the weather is painted. Combine with zoom: false when a room view makes no sense.

Sub-areas

A room with sub_area: true is a named outline inside another room (kitchen corner, shower, dining area): dashed outline, no tint, no walls, not counted in the chips. A tap opens the room that contains it, and it follows that room when you move it in the editor. Any polygon works:

rooms:
  - name: Kitchen
    sub_area: true
    poly: [[10, 10], [230, 10], [230, 90], [90, 90], [90, 170], [10, 170]]
    label: [150, 50]

Editor: Add › Furniture › Sub-areas (Kitchen 300 × 200, Shower 90 × 90, Dining area… then draw it like a rectangle), or tick Sub-area on a room.

Walls

Plain thick segments. They carry nothing but their layer and an optional group (5th value).

walls:
  - [0, 0, 500, 0]
  - [500, 0, 500, 420, ground_floor]

Every opening cuts the wall it sits on, like on an architect's plan. Editor: M; a selected wall offers To boundary and Split in two.

Boundaries and fences

Property limits, fences, hedges: thinner segments, same format as walls (fences). Editor: L; To wall turns one into a wall.

fences:
  - [-300, -200, 900, -200]

Openings

Windows, doors and gates drawn on a wall, with their contact, shutter or motorised entity.

openings:
  - type: window                         # window | door | gate
    seg: [90, 0, 410, 0]                 # its two ends, on the wall
    name: Living room window
    contact: binary_sensor.living_room_window   # red when open
    shutter: cover.living_room_shutter          # drawn outside, darker when closed
    outside: [0, -1]                     # outside is up: [-1,0] left, [1,0] right, [0,-1] up, [0,1] down
  - type: door
    seg: [500, 100, 500, 190]
    contact: binary_sensor.front_door
    leaves: 1
    swing: right                         # left | right (hinge side seen from inside) | sliding
    outward: false
  - type: gate
    seg: [200, -200, 500, -200]
    entity: cover.gate                   # motorised: used when there is no contact

How an opening looks

State	Drawing
Closed (contact off / closed)	Accent line ("closed" in the legend)
Open (on / open)	Thick red line, animated (pulse by default)
Opening or closing	Yellow dashed moving line
Unavailable or unknown	Grey dashed line
No sensor	Window: two thin lines; door or gate: a thin line with short jambs
Shutter	A band on the outside side, more opaque as it closes (position from current_position, else closed = 0 %), animated while moving

Leaves and swing

Without swing, nothing more is drawn. With it, each leaf and its arc are drawn in thin lines like on an architect's plan: left / right is the hinge side seen from inside (facing outside), leaves: 2 draws two leaves, outward: true opens them outward, sliding draws two offset panels.

Shutters, contacts and motors

• contact: a binary_sensor (door, window, opening, garage_door) or anything whose state is on / open. New in 0.2.0: a list of up to 8 sensors for one opening (a sensor on each leaf): open as soon as one is, closed when one answers and none is open, unavailable only when all are. Counted once in the chips and alerts, one line per sensor in its card.
• shutter: a cover; shutter_only: true draws only the shutter (a shutter on a wall without a modelled window).
• entity: a motorised cover (gate, garage door), used for the state when there is no contact.
• bay: give the same name to every leaf of a bay window: one card, one line in the room view, counted once in the open-openings chip (and one sun patch).

  - type: window
    seg: [600, 0, 840, 0]
    name: Bedroom bay
    contact: [binary_sensor.bedroom_left, binary_sensor.bedroom_right]
    leaves: 2
    swing: sliding

Light keys

New in 0.2.0, used by the ambience light only, all optional:

Key	Meaning
sill · height	Bottom and top of the glazing (cm). Default 90 / 215; 180 cm wide or more = down to the floor
glazed	Door only: full (glazed door) or top (small pane at the top): lets daylight in like a window
overhang · overhang_height	Roof overhang above the opening (cm): blocks the high summer sun
slats	With a shutter: tilt (tilting slats, current_tilt_position) or vented (streaks of light when closed)

Tap and card

An opening with a card (or tap: card) opens its card on tap; otherwise a tap opens the more-info of its contact (else entity, else shutter). See Using the card › Cards and Recipes.

In the editor

Add › Openings offers presets and Create an opening (Editor guide); the French window preset is glazed. When an opening is drawn, its sensors are looked up among the free entities of the room it borders; outside is set away from the indoor room. Click it for its floating toolbar, then Edit (or double-click) for its edit dialog, previewed in its room: tabs General (type, leaves, opening side, outside side, bay), Sensors (contact, Add a sensor, shutter, motorised entity), Light (door glazing, sill, height, overhang, slats), Card and Animation. It suggests a free contact or shutter of the room, or the type matching the contact's device class ("Type from the contact: Door" › Apply).

Texts and info boxes

A text is a free label (street name, "Garden"); with info it becomes an info box, a framed list of live values.

texts:
  - text: Street
    pos: [450, 760]
    size: 1.2                       # font factor, scales with the zoom
  - text: Outside                   # title of the box (optional)
    pos: [1080, -90]
    style: subtle                   # no background
    info:
      - {entity: sensor.outdoor_temperature}           # name, icon and unit from the entity
      - {entity: sensor.living_room_humidity, name: Living room, decimals: 0}
      - {entity: climate.thermostat, attribute: current_temperature, unit: "°C", icon: mdi:thermostat}

Each line shows an icon (from icon, the attribute name, the entity icon or its device class), the name and the value; a tap opens its more-info. Editor: T, or Add › Info box, then + Entity in its edit dialog.

Room labels, colours and legend

Card-wide options (⚙ Settings › Rooms and legend):

room_labels:
  humidity: false        # name, temperature, humidity: false removes it from every label
temperature_tint:
  min: 18                # blue at and below (°C)
  max: 26                # red at and above
legend: false            # hide the legend under the plan

temperature_tint: false turns the tint off (and the gradient of the legend). The legend shows the temperature scale, "closed", "open" and, when the plan has shutters, "shutter down".

Framing

The view is framed on the drawing plus margin (40 cm by default), texts and info boxes included. Visitors zoom with the buttons, Ctrl+wheel or a pinch, and pan by dragging. ⚙ Settings › Interaction can lock the view (Using the card).

Layers and groups

Every element belongs to a fixed layer by kind, in two groups; the overlay group is always above the drawing.

Group	Layers, bottom to top
Drawing (drawing_order)	rooms, sub_areas, halos, furniture, fences, walls, openings
Above the drawing (overlay_order)	room_labels, area_labels (named areas, sub-areas), badges, texts

layers:
  drawing_order: [rooms, sub_areas, furniture, halos, fences, walls, openings]
  hidden: [fences]          # hidden in the view
  locked: [walls, rooms]    # clicks go through in the editor
  view_button: true         # a Layers button for viewers (their choice is kept in their browser)

Per element: hidden: true hides it in the view (it still counts in the chips), level orders it inside its layer (higher is on top; rugs and named areas default to -1).

New in 0.2.0: locked: true on a room, opening, badge, text or piece of furniture keeps it from moving or resizing with the mouse or the arrow keys (it stays editable in its edit dialog; a click goes to what lies underneath). Walls and fences lock by layer (layers.locked).

Groups bind elements so that they select and move together: groups: [{id, name}], group: <id> on an element, a 5th value on a wall or fence. Editor: select several elements, Group (Ctrl+G).