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.
Add README, floor plan reference and Smart Life guide
0xProbability0ddadcb7cc34
diff --git a/README.md b/README.mdnew file mode 100644index 0000000..73652c6--- /dev/null+++ b/README.md@@ -0,0 +1,191 @@+<p align="center">+ <img src="docs/icon.png" width="112" alt="House Control icon">+</p>++<h1 align="center">House Control</h1>++<p align="center">+ A macOS menu bar app that shows your home as a live 3D model<br>+ and controls its lights and air conditioners — Smart Life / Tuya devices included.+</p>++<p align="center">+ <img src="docs/hero.png" alt="The panel, an air conditioner sheet and a colour light sheet">+</p>++## What it does++- **Lives in the menu bar.** Click the house icon and a panel drops down; click anywhere else and it is gone.+- **Your floor plan in 3D.** Rooms, walls, doors, windows and furniture are built from one JSON file.+ Lamps light the scene the way they light the room; an AC that is running blows visible air.+- **Lights.** Tap to toggle, drag across a tile to dim, open a light for brightness, white temperature and colour.+- **Air conditioners.** Power, target temperature, mode and fan speed, with the room temperature from a real sensor if you have one.+- **Scenes.** One tap sets every light and AC — "Cozy", "Movie", "Night", or your own.+- **A visual editor.** Draw the rooms, drop in furniture, place lamps and ACs, and link each one to a real device.+- **Works without any hardware.** Until you sign in, every device is simulated, so you can try everything first.++The app is a small native Swift shell (menu bar item, panel, editor window, device clients) around a+[Three.js](https://threejs.org) web UI. No frameworks, no Electron, no server, no account of its own.++## Requirements++| | |+| --- | --- |+| macOS | 13 Ventura or newer |+| Xcode Command Line Tools | Swift 5.9 or newer — `xcode-select --install` |+| Node.js | 20.19+ or 22.12+ |++## Build and run++```bash+git clone https://github.com/0xProbabillity/house-control.git+cd house-control+./scripts/build-app.sh+open build/HouseControl.app+```++The script builds the web UI with Vite, the native shell with SwiftPM, and assembles an ad-hoc signed+`build/HouseControl.app`. The first build downloads the npm packages; later builds take a few seconds.++To keep it, drag `build/HouseControl.app` into `/Applications`. To start it with your Mac, add it under+**System Settings → General → Login Items**.++There is no Dock icon and no main window: look for the house in the menu bar.++## Using it++| Do this | To get this |+| --- | --- |+| Click the menu bar icon | Open or close the panel |+| Right-click the menu bar icon | Edit Home, Load Floor Plan, Reveal Plan File, Reveal Device Log, Reload, Quit |+| Click a lamp in the 3D view, or its tile | Toggle it |+| Drag sideways across a light tile | Dim it |+| Click the sliders icon on a light tile | Brightness, white temperature, colour |+| Click an AC, or its tile | Open its sheet: temperature, mode, fan speed |+| Click a room | Zoom in on it and list only its devices |+| Drag the 3D view / scroll over it | Rotate / zoom |+| `Esc` | Back, then close |++The menu bar icon shows how many lights are on and the target of the running AC, for example `6 · 23°`.++The gear button in the panel switches between your home and the two bundled demo plans, **Apartment** and **Studio**.++## Make it your home++Right-click the icon and choose **Edit Home…**++<p align="center">+ <img src="docs/editor.png" width="820" alt="The floor plan editor">+</p>++- Drag rooms to move them and drag a corner to resize; everything snaps to 5 cm.+- Where two rooms touch, the wall between them appears by itself. Walls facing the camera are cut away.+- Add doors, windows, furniture, lamps and air conditioners from the list on the left.+- **Save & apply** writes the plan and reloads the panel.++The plan is a single JSON file, `~/Library/Application Support/HouseControl/plan.json`. You can write it by hand,+export it, or import someone else's: see [docs/floor-plan.md](docs/floor-plan.md) for every field.+The demo plans in [`web/public/plans`](web/public/plans) are good starting points.++## Connect real devices (Smart Life / Tuya)++You need the **Smart Life** (or **Tuya Smart**) phone app with your devices already added to it.+No Tuya developer account is required.++1. In the phone app open **Me → ⚙ Settings → Account and Security** and copy the **User Code** at the bottom.+2. In House Control: right-click the icon → **Edit Home… → Smart Life**. Enter the User Code and press **Show QR code**.+3. Scan the code with the phone app (the scanner on its Home tab) and confirm the login.+4. Your devices appear in the editor. Select a lamp or an AC on the plan, pick its device under+ **Smart Life device**, and press **Save & apply**.++From then on the panel controls the real device, and re-reads the state of your devices every 12 seconds while it is open.++More detail — what works with which device, infrared air conditioners, temperature sensors, the Tuya Cloud+alternative, and how to diagnose a device that does not react — is in [docs/smart-life.md](docs/smart-life.md).++## Privacy++House Control talks to Tuya's servers and to nothing else. There is no telemetry and no backend of its own.++Everything personal stays in `~/Library/Application Support/HouseControl/` on your Mac:++| File | Contents |+| --- | --- |+| `plan.json` | Your floor plan, including the IDs of the devices you linked |+| `settings.json` | Which plan is active |+| `smartlife.json` | The Smart Life session tokens. Readable only by you (mode `600`) |+| `tuya.json` | Tuya Cloud project credentials, only if you use that option. Mode `600` |+| `events.log` | Commands sent to real devices and the cloud's answers. No tokens |++None of these are part of this repository, and the build does not embed them in the app.+**Sign out** in the editor deletes `smartlife.json`. Deleting the folder resets the app to the demo plan.++## Development++```+web/ the UI: Three.js scene, panel, editor (Vite, plain ES modules)+macos/ the native shell: menu bar item, panel, editor window, Smart Life and Tuya clients (SwiftPM)+scripts/ build-app.sh assembles the .app, make-icon.swift draws the icon+docs/ floor plan reference, Smart Life guide, screenshots+```++Work on the UI in a browser with hot reload — the native bridge is a no-op there and all devices are simulated:++```bash+cd web+npm install+npm run dev+```++Then open `http://localhost:5199/`. Add `?plan=studio` for the second demo plan, `?mode=editor` for the editor,+or `?device=living.ac` to start on a device's sheet. Set `PORT` to use another port.++Environment variables understood by the app:++| Variable | Effect |+| --- | --- |+| `HOUSE_DEV_URL=http://localhost:5199/` | Load the UI from the dev server instead of the bundle |+| `HOUSE_WEB_DIR=/path/to/dist` | Load the UI from another folder |+| `HOUSE_DATA_DIR=/some/folder` | Keep plan, session and log there instead of Application Support, and do not persist panel state. Handy for a clean test run |+| `HOUSE_OPEN_ON_LAUNCH=1` | Open the panel at launch |+| `HOUSE_OPEN_EDITOR=1` | Open the editor at launch (`smartlife` opens it on the Smart Life section) |+| `HOUSE_OPEN_DEVICE=<id>` | Start the panel on that light's or AC's sheet |+| `HOUSE_PIN=1` | Keep the panel open when it loses focus |+| `HOUSE_DOCK=1` | Show a Dock icon, so UI automation tools can see the app |++For example, a throw-away instance on the demo plan, pinned open:++```bash+HOUSE_DATA_DIR=/tmp/house-demo HOUSE_PIN=1 HOUSE_OPEN_ON_LAUNCH=1 build/HouseControl.app/Contents/MacOS/HouseControl+```++The binary has a few offline self-checks and one read-only diagnostic:++| Command | Prints |+| --- | --- |+| `HouseControl --selftest-mapper` | The Tuya commands built for typical light and AC actions |+| `HouseControl --selftest-infrared` | The key presses sent to an infrared AC, against a simulated cloud remote |+| `HouseControl --selftest-transport` | The Smart Life request envelope for fixed inputs, to compare with the reference SDK |+| `HouseControl --diagnose <device id>…` | What Smart Life reports for those devices. Reads only; sends nothing |++## Limitations++- macOS only, and built from source: there is no signed, notarized download.+- Rooms are axis-aligned rectangles. An L-shaped room is two rooms.+- Smart Life is the only device backend. Devices are reached through Tuya's cloud, not over the local network,+ so they need an internet connection.+- Infrared air conditioners are one-way: the app shows what was last sent, not what the unit is doing.++## Acknowledgements and disclaimer++The Smart Life sign-in is a Swift port of Tuya's open-source+[`tuya-device-sharing-sdk`](https://github.com/tuya/tuya-device-sharing-sdk), the library behind the Tuya+integration in Home Assistant, and identifies itself to Tuya the same way. The 3D view is built with+[Three.js](https://threejs.org); the icons are from [Lucide](https://lucide.dev).++This project is not affiliated with or endorsed by Tuya, Smart Life or Home Assistant. It relies on an+interface Tuya can change at any time. Use it at your own risk.++## License++[MIT](LICENSE)diff --git a/docs/editor.png b/docs/editor.pngnew file mode 100644index 0000000..847de48Binary files /dev/null and b/docs/editor.png differdiff --git a/docs/floor-plan.md b/docs/floor-plan.mdnew file mode 100644index 0000000..e77d250--- /dev/null+++ b/docs/floor-plan.md@@ -0,0 +1,182 @@+# 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`](../web/public/plans/home.json) and+ [`studio.json`](../web/public/plans/studio.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.++<p align="center">+ <img src="studio.png" width="300" alt="The Studio demo plan">+</p>++## 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++```jsonc+{+ "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 |++## `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` |++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` |++## `furniture`++Decoration only. Every piece has `type`, `pos` (`[x, z]` of its centre) and an optional `rot`.++| `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` |+| `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 |+| `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` |+| `tuya` | Link to a real device — 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 has a `tuya` object. The editor fills it in when you pick a device;+by hand it looks like this:++```jsonc+{ "id": "living.floor", "name": "Floor lamp", "room": "living", "type": "floor", "pos": [5.8, 0.6],+ "tuya": { "deviceId": "<device id>" } }++{ "id": "living.ac", "name": "Living AC", "room": "living", "wall": "west", "pos": [0, 0.8],+ "tuya": { "deviceId": "<device id>", "sensorId": "<id of a temperature sensor in the room>" } }+```++| Field | Meaning |+| --- | --- |+| `deviceId` | The Smart Life device |+| `sensorId` | ACs only, optional: a temperature sensor whose reading is shown as the room temperature |+| `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 `tuya` object stay simulated, so a plan can mix real and imaginary ones.++Device IDs identify your hardware. Remove the `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.diff --git a/docs/hero.png b/docs/hero.pngnew file mode 100644index 0000000..ab5de77Binary files /dev/null and b/docs/hero.png differdiff --git a/docs/smart-life.md b/docs/smart-life.mdnew file mode 100644index 0000000..df98da5--- /dev/null+++ b/docs/smart-life.md@@ -0,0 +1,117 @@+# Smart Life / Tuya devices++House Control controls the devices of a **Smart Life** or **Tuya Smart** account. Until you connect one,+every device in the plan is simulated.++## Signing in++You need the phone app with your devices already added to it. No Tuya developer account is required.++1. In the phone app: **Me → ⚙ Settings → Account and Security**. Copy the **User Code** at the bottom of the screen.+2. In House Control: right-click the menu bar icon → **Edit Home… → Smart Life**. Enter the User Code and press **Show QR code**.+3. Scan the code with the phone app (the scanner icon on its Home tab) and confirm.+4. The editor lists the devices of the account.++This is the sign-in the Tuya integration of Home Assistant uses. `SmartLifeService.swift` is a Swift port of+Tuya's open-source [`tuya-device-sharing-sdk`](https://github.com/tuya/tuya-device-sharing-sdk) and presents+the same client identifier to Tuya. Requests are AES-GCM encrypted and HMAC-SHA256 signed.++The session is stored in `~/Library/Application Support/HouseControl/smartlife.json`, readable only by your+user, and is refreshed automatically. **Sign out** in the editor deletes it.++## Linking devices to the plan++Select a lamp or an AC in the editor, choose its device under **Smart Life device**, and press **Save & apply**.++- A lamp's sliders follow the plan, not the device: give the light the capabilities it really has+ (`brightness`, `temp`, `color`). A smart plug has none and only switches.+- For an AC you can also enter the device ID of a **temperature sensor** in the same room. The sheet then+ shows the measured room temperature instead of an estimate.++While the panel is open, the app reads the state of all linked devices every 12 seconds, so changes made in+the phone app or on a wall switch show up.++## What is supported++| Device | Works | How |+| --- | --- | --- |+| Smart plugs, switches | On / off | `switch_1`, `switch`, or the code named in `codes.switch` |+| Bulbs, LED strips | On / off, brightness, white temperature, colour | `switch_led`, `bright_value(_v2)`, `temp_value(_v2)`, `colour_data(_v2)` |+| Wi-Fi air conditioners | Power, temperature, mode, fan speed, sleep, eco | `switch`, `temp_set`, `mode`, `fan_speed_enum` / `windspeed`, `sleep`, `eco` |+| Infrared air conditioners | Power, temperature, mode, fan speed | `PowerOn`, `PowerOff`, `T`, `M`, `F` — see below |+| Temperature sensors | Room temperature for an AC | `temp_current`, `va_temperature` |++Value ranges come from each device's own specification, so bulbs with a 0–255 scale and bulbs with a+10–1000 scale behave the same.++An AC only shows the controls its device has a function for. Airflow direction, Sleep and Eco are simulated+extras of the demo; on a real AC they appear only when the device offers them.++## Infrared air conditioners++An AC driven by an infrared blaster ("universal remote") is not a device with a state of its own. Tuya keeps+a *virtual remote* in the cloud; every change is a key press that the blaster transmits, and the cloud works+out the infrared code from the state it remembers for that remote. That shapes how the app behaves:++- **One key at a time.** A change of mode and temperature is two transmissions, a second apart. Expect one+ beep per key.+- **Nothing is sent while the AC is off.** Change the fan speed of an AC that is off and it is sent along+ when you switch it on.+- **The state is assumed.** Infrared is one-way. The panel shows what was last sent from this app; it does+ not notice the physical remote, and it does not see changes made in the phone app.+- **A refused key is replayed.** If the cloud answers `2008` ("command or value not support") the state it+ remembers usually differs from the app's — for example it is in Auto or Dry mode, where many units have a+ fixed temperature. The app then re-sends its whole state (power, mode, temperature, fan) and tries once+ more. If the key is refused again, that remote really has no infrared code for the setting; the panel+ says so and returns to the previous value.+- **The numbering is the common one:** modes `0` cool, `1` heat, `2` auto, `3` fan, `4` dry; fan speeds+ `0` auto, `1` low, `2` medium, `3` high. A unit that lacks one of them refuses it.+- **No airflow, sleep or eco.** Tuya's infrared key set has no such keys, so the sheet does not show them.++## When a device does not react++**Reveal Device Log** in the menu bar icon's right-click menu opens `events.log`: every command sent to a+real device and what the cloud answered. That is the first place to look.++```+2026-01-12T21:14:03+02:00 kitchen.ac T=25 → command or value not support (code 2008)+2026-01-12T21:14:03+02:00 kitchen.ac target refused (2008): replaying fan, mode, on+2026-01-12T21:14:04+02:00 kitchen.ac PowerOn=PowerOn → ok+2026-01-12T21:14:05+02:00 kitchen.ac M=0 → ok+2026-01-12T21:14:06+02:00 kitchen.ac F=0 → ok+2026-01-12T21:14:07+02:00 kitchen.ac T=25 → ok+```++| Code | Meaning | What to do |+| --- | --- | --- |+| `2001` | The device is offline | Check its power and Wi-Fi in the phone app. A device paired only over Bluetooth cannot be reached through the cloud |+| `2008` | The device does not accept that command or value | For a lamp: remove the capability it does not have. For an infrared AC: see above |+| `1109` | Invalid parameter | Usually several infrared keys in one request; should not happen with this app |++To see exactly what the cloud knows about a device — its category, its functions and their ranges, its+current status — run the read-only diagnostic with its device ID (shown in the editor):++```bash+build/HouseControl.app/Contents/MacOS/HouseControl --diagnose <device id>+```++It sends nothing to the device.++## Alternative: a Tuya Cloud project++If you have a cloud project on [platform.tuya.com](https://platform.tuya.com) with your app account linked+to it (**Devices → Link App Account**), you can use its credentials instead: **Edit Home… → Smart Life →+Advanced**. Enter the Access ID, the Access Secret and the data center of the project.++The QR sign-in takes precedence when both are set. The cloud-project client (`TuyaService.swift`) covers the+same devices but has seen far less real-world use than the QR route.++## How it is put together++| File | Role |+| --- | --- |+| `SmartLifeService.swift` | QR login, token refresh, the encrypted request envelope, device list / status / specification / commands |+| `TuyaService.swift` | The Tuya Cloud project client, and `TuyaMapper`, which translates between the app's state and Tuya data points |+| `InfraredRemote.swift` | Key sequencing for infrared ACs |+| `AppDelegate.swift` | Queues commands per device, polls state, reports results to the panel |+| `web/src/store.js` | Coalesces changes into few commands and rolls back the ones a device refuses |diff --git a/docs/studio.png b/docs/studio.pngnew file mode 100644index 0000000..194cfbdBinary files /dev/null and b/docs/studio.png differ