jet/noisebell
jet/noisebell
1
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat: add documentation for pi relay and home automation

Browse source
This commit is contained in:
Jet 2026-03-24 00:51:27 -07:00
parent 4f7ac0e7d7
commit 3dcd3f00d8
No known key found for this signature in database
3 changed files with 80 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

69
pi/README.md
View file

@ -102,6 +102,12 @@ From your laptop:
scripts/deploy-pios-pi.sh pi@noisebell-pi.local
```
If Home Assistant is on a fixed LAN IP, set that explicitly during deploy:
```sh
HOME_ASSISTANT_BASE_URL=http://10.21.0.43:8123 scripts/deploy-pios-pi.sh pi@100.66.45.36
```
If you only know the IP:
```sh
@ -186,13 +192,15 @@ The optional relay service accepts authenticated webhooks from cache-service and
|---|---|---|
| `NOISEBELL_RELAY_PORT` | `8090` | HTTP port for the relay webhook endpoint |
| `NOISEBELL_RELAY_BIND_ADDRESS` | `0.0.0.0` | HTTP bind address |
| `NOISEBELL_RELAY_TARGET_BASE_URL` | `http://homeassistant.local:8123` | Base URL for Home Assistant |
| `NOISEBELL_RELAY_TARGET_BASE_URL` | `http://10.21.0.43:8123` | Base URL for Home Assistant |
| `NOISEBELL_RELAY_TARGET_WEBHOOK_ID` | required | Home Assistant webhook ID |
| `NOISEBELL_RELAY_INBOUND_API_KEY` | required | Bearer token expected from cache-service |
| `NOISEBELL_RELAY_RETRY_ATTEMPTS` | `3` | Forward retry count |
| `NOISEBELL_RELAY_RETRY_BASE_DELAY_SECS` | `1` | Exponential backoff base delay |
| `NOISEBELL_RELAY_HTTP_TIMEOUT_SECS` | `10` | Outbound request timeout |
If `.local` resolution is reliable on your Pi, you can override the deploy default with `HOME_ASSISTANT_BASE_URL=http://homeassistant.local:8123`.
Example cache target for the relay:
```nix
@ -206,6 +214,65 @@ Example cache target for the relay:
}
```
## Home Assistant workflow
The working Home Assistant path is:
```text
Pi door sensor -> cache-service -> Pi relay -> Home Assistant webhook automation
```
This keeps cache-service as the fanout source while still letting Home Assistant stay LAN-only.
Setup summary:
1. Pi still posts raw door events to cache via `NOISEBELL_ENDPOINT_URL`
2. cache-service fans out to `http://noisebell-pi:8090/webhook` using `relay-webhook-secret.age`
3. `noisebell-relay` forwards the payload to Home Assistant using `homeassistant-webhook-id.age`
4. Home Assistant automation triggers on the webhook and switches devices based on `trigger.json.status`
Payload received by Home Assistant:
```json
{
"status": "open",
"timestamp": 1774336193
}
```
Example Home Assistant automation:
```yaml
alias: noisebell
description: ""
triggers:
- trigger: webhook
allowed_methods:
- POST
local_only: false
webhook_id: "-roWWM0JVCWSispwyHXlcKtjI"
conditions: []
actions:
- if:
- condition: template
value_template: "{{ trigger.json.status == 'open' }}"
then:
- action: switch.turn_on
target:
entity_id: switch.mini_smart_plug_socket_1
else:
- if:
- condition: template
value_template: "{{ trigger.json.status == 'closed' }}"
then:
- action: switch.turn_off
target:
entity_id: switch.mini_smart_plug_socket_1
mode: single
```
Important: Home Assistant webhook IDs are exact. If the automation shows a leading `-`, keep that same leading `-` in `homeassistant-webhook-id.age`.
## API
All endpoints require `Authorization: Bearer <token>`.