Skip to content

Commit d5fe72d

Browse files
mabry1985claude
mabry1985
and
claude
authored
docs: add calendar module docs and expand HA integration docs (#58)
- Add docs/modules/calendar.md with full API reference, data model, event types, job scheduling details, and WebSocket events - Expand docs/modules/sensors.md HA section from a stub into a full setup guide covering WebSocket config, ha: namespace, initial state fetch, and auth failure behaviour - Restructure docs/integrations/home-assistant.md to document both the direct WebSocket integration (recommended) and the push-via-REST alternative, with connection behaviour notes Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 2246d60 commit d5fe72d

File tree

3 files changed

+264
-17
lines changed

3 files changed

+264
-17
lines changed

‎docs/integrations/home-assistant.md‎

Lines changed: 71 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -2,30 +2,85 @@
22

33
This guide shows you how to bridge Home Assistant sensor data into homeMaker's sensor registry. After completing it, HA entity states will appear in the homeMaker Sensors view and feed into the context aggregator.
44

5-
## How it works
5+
## Two integration approaches
66

7-
homeMaker exposes two sensor API endpoints:
7+
| Approach | How it works | Best for |
8+
| -------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------- |
9+
| **Direct WebSocket** | homeMaker connects to HA's WebSocket API and subscribes to state changes | Most users — zero HA configuration needed |
10+
| **Push via REST** | HA automations call homeMaker's sensor API on state change | Environments where homeMaker can't reach HA directly |
811

9-
- `POST /api/sensors/register` — register a sensor on startup
10-
- `POST /api/sensors/report` — post a periodic reading
12+
---
1113

12-
You configure Home Assistant automations to call these endpoints whenever a sensor updates.
14+
## Direct WebSocket integration (recommended)
15+
16+
homeMaker can connect directly to Home Assistant and receive live entity updates — no HA automations required.
17+
18+
### Prerequisites
19+
20+
- Home Assistant running and reachable from the homeMaker server (same network or via Tailscale)
21+
- A long-lived access token from your HA profile (**Profile → Long-Lived Access Tokens**)
22+
23+
### Set up the connection
24+
25+
1. Open homeMaker and go to **Settings → Integrations → Home Assistant**.
26+
2. Enter your HA URL (e.g. `http://homeassistant.local:8123`) and your token.
27+
3. Click **Test connection** to verify. The test runs server-side — this avoids CORS issues that would block a browser-to-HA probe on most local installs.
28+
4. Enable the toggle to start the live connection.
29+
30+
Once connected, homeMaker fetches the current state of all synced entities immediately, then streams future changes in real time.
31+
32+
### Select which entities to sync
33+
34+
After connecting, homeMaker lists your HA entities. Toggle the ones you want to track as sensors. Your selection is saved in Settings and persists across restarts.
35+
36+
### Entity naming
37+
38+
All HA entities appear in homeMaker with a `ha:` prefix:
39+
40+
```
41+
ha:sensor.living_room_temperature
42+
ha:binary_sensor.front_door
43+
ha:light.kitchen_overhead
44+
```
45+
46+
This namespace keeps HA sensors distinct from directly-registered IoT devices.
47+
48+
### Connection behaviour
49+
50+
- **On connect:** homeMaker fetches current state for all selected entities before subscribing to changes, so readings are accurate from the start.
51+
- **On auth failure:** the connection stops permanently. Correct the token in Settings and re-enable the integration to reconnect. Invalid tokens are never retried automatically.
52+
- **On network error:** homeMaker reconnects automatically with exponential backoff.
53+
54+
---
55+
56+
## Push via REST (alternative)
57+
58+
Use this approach if homeMaker cannot reach HA directly (e.g. reverse-proxy or firewall restrictions).
1359

14-
## Prerequisites
60+
### Prerequisites
1561

1662
- Home Assistant running on your local network
1763
- homeMaker accessible from Home Assistant (same network, or via Tailscale)
1864
- A long-lived access token from your HA profile
1965

20-
## Step 1: Register a sensor
66+
### How it works
67+
68+
homeMaker exposes two sensor API endpoints:
69+
70+
- `POST /api/sensors/register` — register a sensor on startup
71+
- `POST /api/sensors/report` — post a periodic reading
72+
73+
You configure Home Assistant automations to call these endpoints whenever a sensor updates.
74+
75+
### Step 1: Register a sensor
2176

2277
Call `POST /api/sensors/register` once per sensor, typically in a startup automation.
2378

2479
```yaml
2580
# configuration.yaml — REST command for registration
2681
rest_command:
2782
register_homemaker_sensor:
28-
url: "http://homemaker:8579/api/sensors/register"
83+
url: 'http://homemaker:8579/api/sensors/register'
2984
method: POST
3085
headers:
3186
Content-Type: application/json
@@ -38,30 +93,30 @@ rest_command:
3893
}
3994
```
4095
41-
## Step 2: Report readings via automation
96+
### Step 2: Report readings via automation
4297
4398
Create one automation per sensor (or use a template automation):
4499
45100
```yaml
46101
# automations.yaml
47-
- alias: "Report living room temperature to homeMaker"
102+
- alias: 'Report living room temperature to homeMaker'
48103
trigger:
49104
- platform: state
50105
entity_id: sensor.living_room_temperature
51106
action:
52107
- service: rest_command.report_homemaker_sensor
53108
data:
54-
sensor_id: "ha:sensor.living_room_temperature"
109+
sensor_id: 'ha:sensor.living_room_temperature'
55110
value: "{{ states('sensor.living_room_temperature') }}"
56-
unit: "°F"
111+
unit: '°F'
57112
```
58113
59114
Add the matching REST command:
60115
61116
```yaml
62117
rest_command:
63118
report_homemaker_sensor:
64-
url: "http://homemaker:8579/api/sensors/report"
119+
url: 'http://homemaker:8579/api/sensors/report'
65120
method: POST
66121
headers:
67122
Content-Type: application/json
@@ -73,7 +128,7 @@ rest_command:
73128
}
74129
```
75130
76-
## Step 3: Register on HA startup
131+
### Step 3: Register on HA startup
77132
78133
To ensure sensors are registered after a restart, add a trigger to the automation:
79134
@@ -85,7 +140,7 @@ trigger:
85140
entity_id: sensor.living_room_temperature
86141
```
87142
88-
## Sensor naming convention
143+
### Sensor naming convention
89144
90145
Use `ha:domain.entity_id` for all HA-sourced sensors:
91146

@@ -98,7 +153,7 @@ ha:sensor.electricity_usage
98153
99154
This namespace keeps HA sensors distinct from directly-registered IoT devices.
100155
101-
## Verify in homeMaker
156+
### Verify in homeMaker
102157
103158
1. Open homeMaker at `http://homemaker:8578`.
104159
2. Click **Sensors** in the sidebar.

‎docs/modules/calendar.md‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
# Calendar
2+
3+
Schedule household events, track milestones, and automate recurring jobs from a single view.
4+
5+
## Event types
6+
7+
| Type | Description |
8+
| ------------- | ---------------------------------------------------------------- |
9+
| `custom` | General household events (appointments, deliveries, etc.) |
10+
| `milestone` | Project milestones for house improvement work |
11+
| `maintenance` | Scheduled maintenance tasks (linked from the Maintenance module) |
12+
| `job` | Timed automations that execute a command or trigger an agent |
13+
| `feature` | Feature work milestones (AI-generated) |
14+
| `ceremony` | Recurring AI pipeline events |
15+
| `google` | Events synced from Google Calendar |
16+
17+
## Data model
18+
19+
| Field | Type | Description |
20+
| ------------- | ---------------------- | ------------------------------------------------ |
21+
| `id` | string | UUID |
22+
| `projectPath` | string | Project this event belongs to |
23+
| `title` | string | Event title |
24+
| `date` | string | Start date (`YYYY-MM-DD`) |
25+
| `endDate` | string \| undefined | End date for multi-day events (`YYYY-MM-DD`) |
26+
| `type` | CalendarEventType | See event types table above |
27+
| `time` | string \| undefined | Time in `HH:mm` 24-hour format (job events only) |
28+
| `jobAction` | JobAction \| undefined | Action to run (job events only) |
29+
| `jobStatus` | string \| undefined | `pending`, `running`, `completed`, `failed` |
30+
| `description` | string \| undefined | Notes or details |
31+
| `color` | string \| undefined | Display color (hex, e.g. `#4f46e5`) |
32+
| `url` | string \| undefined | Link to an external resource |
33+
| `allDay` | boolean \| undefined | Whether the event spans the full day |
34+
| `createdAt` | string | ISO-8601 creation timestamp |
35+
| `updatedAt` | string | ISO-8601 last-updated timestamp |
36+
37+
## API reference
38+
39+
All calendar endpoints accept JSON bodies and require `projectPath`.
40+
41+
### List events
42+
43+
```
44+
POST /api/calendar/list
45+
```
46+
47+
```json
48+
{
49+
"projectPath": "/home/user/my-house",
50+
"startDate": "2026-03-01",
51+
"endDate": "2026-03-31",
52+
"types": ["custom", "maintenance"]
53+
}
54+
```
55+
56+
`startDate`, `endDate`, and `types` are all optional. Omitting them returns all events.
57+
58+
### Create event
59+
60+
```
61+
POST /api/calendar/create
62+
```
63+
64+
```json
65+
{
66+
"projectPath": "/home/user/my-house",
67+
"title": "HVAC filter replacement",
68+
"date": "2026-04-01",
69+
"type": "custom",
70+
"description": "Replace 20x25x1 MERV-13 filters",
71+
"color": "#f97316"
72+
}
73+
```
74+
75+
Required fields: `projectPath`, `title`, `date`, `type`.
76+
77+
### Create a scheduled job
78+
79+
Job events run an action at a specific time. Set `type: "job"` and supply `time` (HH:mm) and `jobAction`:
80+
81+
```json
82+
{
83+
"projectPath": "/home/user/my-house",
84+
"title": "Nightly backup",
85+
"date": "2026-04-01",
86+
"type": "job",
87+
"time": "02:30",
88+
"jobAction": {
89+
"type": "run-command",
90+
"command": "npm run backup"
91+
}
92+
}
93+
```
94+
95+
Available job action types:
96+
97+
| `type` | Required fields | Description |
98+
| ---------------- | ------------------------- | ------------------------------- |
99+
| `run-command` | `command`, optional `cwd` | Run a shell command |
100+
| `start-agent` | `featureId` | Start an AI agent for a feature |
101+
| `run-automation` | `automationId` | Trigger a saved automation |
102+
103+
> **Note:** `run-command` only accepts a single command with no shell metacharacters (`;`, `&&`, `|`, `>`, `$`). Use a script file for complex logic.
104+
105+
### Update event
106+
107+
```
108+
POST /api/calendar/update
109+
```
110+
111+
```json
112+
{
113+
"projectPath": "/home/user/my-house",
114+
"id": "evt_abc123",
115+
"title": "HVAC filter — done",
116+
"color": "#22c55e"
117+
}
118+
```
119+
120+
Pass only the fields you want to change alongside `projectPath` and `id`.
121+
122+
### Delete event
123+
124+
```
125+
POST /api/calendar/delete
126+
```
127+
128+
```json
129+
{
130+
"projectPath": "/home/user/my-house",
131+
"id": "evt_abc123"
132+
}
133+
```
134+
135+
### Run a job manually
136+
137+
Trigger a pending job event immediately, without waiting for its scheduled time:
138+
139+
```
140+
POST /api/calendar/run-job
141+
```
142+
143+
```json
144+
{
145+
"projectPath": "/home/user/my-house",
146+
"id": "evt_abc123"
147+
}
148+
```
149+
150+
Returns immediately — job execution continues in the background. Poll `POST /api/calendar/list` to check `jobStatus`.
151+
152+
## WebSocket events
153+
154+
| Event | Payload |
155+
| ------------------------ | --------------------------------- |
156+
| `calendar:event:created` | `{ eventId, projectPath, event }` |
157+
| `calendar:event:updated` | `{ eventId, projectPath, event }` |
158+
| `calendar:event:deleted` | `{ eventId, projectPath }` |
159+
160+
## Next steps
161+
162+
- [Maintenance module](./maintenance.md) — link recurring tasks to calendar dates
163+
- [Board module](../platform/board.md) — track house projects alongside your schedule

‎docs/modules/sensors.md‎

Lines changed: 30 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,36 @@ GET /api/sensors/:id/history?from=2026-03-01&to=2026-03-15
5656

5757
## Home Assistant integration
5858

59-
homeMaker subscribes to the Home Assistant WebSocket API to receive state changes from HA entities. Configure the HA URL and token in the app settings. HA entity state changes are mapped to sensor readings automatically.
59+
homeMaker can connect directly to your Home Assistant instance over its WebSocket API. When connected, entity state changes are mapped to sensor readings automatically — no HA automations required.
60+
61+
### Configure the connection
62+
63+
1. Open homeMaker and go to **Settings → Integrations → Home Assistant**.
64+
2. Enter your HA URL (e.g. `http://homeassistant.local:8123`) and a long-lived access token.
65+
3. Click **Test connection** — homeMaker sends a server-side probe to verify credentials (browser-to-HA calls are blocked by CORS on most local HA installs).
66+
4. Enable the toggle to start the live connection.
67+
68+
### Entity ID namespace
69+
70+
All HA-sourced sensors use the `ha:` prefix to avoid collisions with directly-registered IoT devices:
71+
72+
```
73+
ha:sensor.living_room_temperature
74+
ha:binary_sensor.front_door
75+
ha:light.kitchen_overhead
76+
```
77+
78+
### Initial state
79+
80+
On connect, homeMaker fetches the current state of all synced entities via `get_states` before subscribing to `state_changed` events. This ensures sensors show accurate readings immediately rather than waiting for the first change.
81+
82+
### Auth failure behaviour
83+
84+
If the token is rejected, the connection stops permanently and will not auto-retry. Correct the token in Settings and re-enable the integration to reconnect.
85+
86+
### Alternative: push model
87+
88+
If you prefer HA to push data to homeMaker (rather than homeMaker pulling from HA), use the REST API approach instead. See the [Home Assistant integration guide](../integrations/home-assistant.md).
6089

6190
## WebSocket events
6291

0 commit comments

Comments
 (0)