Your home as a live 3D model in the Mac menu bar and on iPhone — lights and ACs via Smart Life, Home Assistant, Philips Hue and Apple Home.
The floor plan file
A home is one JSON document. The 3D scene, the panel and the editor are all built from it, so swapping the file swaps the home.
- Your plan:
~/Library/Application Support/HouseControl/plan.json - Bundled demos:
web/public/plans/home.json,studio.jsonand, on two floors,house.json
You rarely need to write it by hand — Edit Home… does it for you — but it is plain, stable and easy to generate or version. Load a file with Load Floor Plan… in the menu bar icon's right-click menu, or with Import… in the editor.
Coordinates
Everything is in metres, seen from above: x grows to the right (east), z grows downwards (south).
Heights (y, sill, head) are metres above the floor. Angles are degrees.
A complete small example
{
"name": "Home",
"wallHeight": 2.6,
"interiorWallHeight": 1.25,
"outdoorTemp": 29,
"camera": { "azimuth": 34, "elevation": 47 },
"rooms": [
{ "id": "living", "name": "Living", "rect": [0, 0, 6.4, 4.6], "floor": "oak" },
{ "id": "bath", "name": "Bathroom", "rect": [6.4, 0, 2.2, 3.6], "floor": "tile" }
],
"openings": [
{ "type": "door", "from": [6.4, 1.0], "to": [6.4, 1.9] },
{ "type": "window", "from": [0, 1.0], "to": [0, 2.6], "sill": 0.85, "head": 2.1 }
],
"furniture": [
{ "type": "sofa", "pos": [3.9, 2.4], "rot": -90, "width": 2.5, "color": "#8b93a7" },
{ "type": "rug", "pos": [2.6, 2.4], "size": [2.4, 1.6] }
],
"lights": [
{ "id": "living.main", "name": "Ceiling", "room": "living", "type": "ceiling", "pos": [2.9, 2.3],
"capabilities": ["brightness", "temp"] },
{ "id": "living.floor", "name": "Floor lamp", "room": "living", "type": "floor", "pos": [5.8, 0.6] },
{ "id": "living.tv", "name": "TV backlight", "room": "living", "type": "strip", "pos": [0.13, 2.3],
"y": 1.05, "rot": 90, "length": 1.5, "capabilities": ["brightness", "color"], "color": "#7b5cff" }
],
"acs": [
{ "id": "living.ac", "name": "Living AC", "room": "living", "wall": "west", "pos": [0, 0.8], "y": 2.2 }
],
"scenes": [
{ "id": "movie", "name": "Movie", "icon": "film",
"lights": { "*": { "on": false }, "living.tv": { "on": true, "brightness": 0.9, "color": "#6a4cff" } },
"acs": { "*": { "target": 23 } } }
]
}
Top level
| Field | Default | Meaning |
|---|---|---|
name |
"Home" |
Shown in the panel header |
wallHeight |
2.6 |
Height of the outer walls |
interiorWallHeight |
1.25 |
How much of the inner walls is drawn, so they do not hide the rooms |
outdoorTemp |
27 |
Used to estimate the room temperature of an AC that has no sensor |
camera.azimuth, camera.elevation |
34, 47 |
Default view. Walls facing the camera are cut away, so the azimuth decides which side is open |
levels |
one floor | The floors of a home on several, lowest first. See Floors |
levels: floors
A home on one floor needs nothing here. A house on several lists its floors, lowest first:
"levels": [
{ "id": "ground", "name": "Ground floor" },
{ "id": "upper", "name": "First floor", "wallHeight": 2.5 }
]
| Field | Meaning |
|---|---|
id |
Unique. Rooms, furniture and openings refer to it with "level" |
name |
Shown on the floor buttons of the panel and the editor |
wallHeight |
Optional: this floor's own wall height (the home's wallHeight otherwise) |
Every room, piece of furniture and opening then says which floor it is on with "level": "<id>"; without it, it
is on the first. Lamps and ACs are on their room's floor. All floors share one grid, so a room upstairs at
[0, 0, 4, 3] sits right above the room at [0, 0, 4, 3] downstairs. Each floor stands on the one under it
(its walls plus a 30 cm slab); the 3D view shows one floor at a time, with the floors under it, and the editor
draws the floor below faintly so walls and stairs line up. Stairs are furniture on the lower floor
("type": "stairs").
rooms
| Field | Meaning |
|---|---|
id |
Unique. Lights and ACs refer to it |
name |
Shown in the room filter |
rect |
[x, z, width, depth] |
floor |
oak, walnut, tile or stone |
level |
The floor (storey) it is on, on a home with several |
Rooms are rectangles. Where two of them touch, an inner wall appears on its own; make an L-shaped room out of two.
openings
A gap in a wall, given by its two end points on that wall. It must be horizontal or vertical.
| Field | Meaning |
|---|---|
type |
door, window, or open (a doorway without a door, or a missing piece of wall) |
from, to |
[x, z] end points |
sill, head |
Bottom and top of a window. Defaults 0.85 and 2.1 |
level |
Its floor, on a home with several |
furniture
Decoration only. Every piece has type, pos ([x, z] of its centre), an optional rot and, on a home with
several floors, its level.
type |
Extra options |
|---|---|
sofa |
width, color |
armchair |
color |
coffeeTable |
width |
rug |
size ([width, depth]), color |
tv, sideboard, dresser, desk, vanity |
width |
diningSet |
width, chairs |
island |
width, stools |
kitchen |
width, upper (wall cabinets, true by default) |
bed |
width, color |
wardrobe, bookshelf |
width, height |
plant |
height |
stairs |
width, depth (its length), height (up to the floor above by default). They climb away from the front |
fridge, nightstand, bathtub, toilet |
— |
lights
| Field | Meaning |
|---|---|
id |
Unique |
name |
Shown on the tile |
room |
The id of its room |
type |
ceiling, pendant, spots, floor, table or strip |
pos |
[x, z] |
y |
Height, if the default for the type does not fit |
rot |
Rotation, for strips and spots |
length |
Length of a strip |
capabilities |
Any of brightness, temp, color. Leave it out for a plain smart plug that only switches |
color |
Initial colour of a colour light |
link, tuya |
Link to a real device — see below |
acs
| Field | Meaning |
|---|---|
id, name, room |
As for lights |
wall |
The wall it hangs on: north, south, east or west |
pos |
[x, z], on that wall |
y |
Height. Default 2.2 |
min, max |
Range of the target temperature. Defaults 16 and 30 |
link, tuya |
Link to a real device — see below |
sensor |
A thermometer for the room — see below |
scenes
| Field | Meaning |
|---|---|
id, name |
Unique id and the label of the button |
icon |
sun, sofa, film, moon, door, table, bed, tv or sparkles |
lights |
Light id → what to set: on, brightness (0–1), temp (2200–6500 K), color (#rrggbb) |
acs |
AC id → what to set: on, target, mode (cool, heat, dry, fan, auto), fan (auto, low, medium, high, turbo) |
In both maps the key "*" applies to every device, and a device's own entry overrides it.
Linking real devices
A light or an AC becomes real when it is linked to a device of a connected platform. The editor fills the link in when you pick a device under Real device; by hand it looks like this:
// Home Assistant (an entity id), Philips Hue (the bridge's light id), Apple Home (HomeKit's service id)
{ "id": "living.floor", "name": "Floor lamp", "room": "living", "type": "floor", "pos": [5.8, 0.6],
"link": { "service": "homeassistant", "id": "light.floor_lamp" } }
// An AC with a thermometer from any platform for its room temperature
{ "id": "living.ac", "name": "Living AC", "room": "living", "wall": "west", "pos": [0, 0.8],
"link": { "service": "homeassistant", "id": "climate.living_room" },
"sensor": { "service": "hue", "id": "<id of a Hue motion sensor's thermometer>" } }
// Smart Life keeps its own object
{ "id": "bed.ac", "name": "Bedroom AC", "room": "bedroom", "wall": "north", "pos": [2, 0],
"tuya": { "deviceId": "<device id>", "sensorId": "<id of a Smart Life temperature sensor in the room>" } }
| Field | Meaning |
|---|---|
link.service |
homeassistant, hue or homekit |
link.id |
The device on that platform |
sensor |
ACs only, optional: { "service", "id" } of a temperature sensor whose reading is shown as the room temperature. A simulated AC can have one too |
tuya.deviceId |
The Smart Life device |
tuya.sensorId |
ACs linked to Smart Life only, optional: a Smart Life temperature sensor |
tuya.codes.switch |
Optional: the data point that switches the device, when it is not the usual one — e.g. "switch_2" for the second gang of a double switch |
Devices without a link stay simulated, so a plan can mix real and imaginary ones, and one home can mix platforms: Hue lamps, a Home Assistant air conditioner and a Smart Life plug side by side.
Device IDs identify your hardware. Remove the link, sensor and tuya objects before you share a plan.
Errors
A plan that does not add up — an unknown room, a duplicate id, an opening that is not axis-aligned — is not rendered half-way: the panel says what is wrong and where, and the editor shows the same in its status bar.