docs(awning): spec for standalone WiFi reed "closed" sensor (Option 1)
ESP32-C3 + weatherproof reed on OmnissiahsReach WiFi (no Zigbee mesh) for true stowed/not-stowed state: BOM, wiring, ESPHome config, HA/bridge integration, optional truthful template cover, and the Option-2 (wire-to-CAN-node) note. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Claude Opus 4.8
@@ -0,0 +1,192 @@
|
||||
# Awning "Closed" Sensor — Spec (Option 1: standalone WiFi reed node)
|
||||
|
||||
**Goal:** give the campsite awning a *true* stowed/not-stowed state instead of the
|
||||
`assumed_state` the CAN cover currently reports. A magnetic reed switch at the
|
||||
fully-retracted position, read by a small ESP running ESPHome over the existing
|
||||
`OmnissiahsReach` WiFi — **no Zigbee mesh, no coordinator, no new ecosystem.**
|
||||
|
||||
This is "Option 1" (standalone node). Option 2 (wire the reed back to a spare GPIO
|
||||
on the CAN node `192.168.69.18` so the cover entity itself becomes truthful) is the
|
||||
more-integrated alternative but needs a 2-wire run from the awning to the control
|
||||
panel; it's noted at the end. Pairs with the current-sensing auto-retract already
|
||||
in `esphome/onecontrol-canbus.yaml` (README "awning" section): current does the
|
||||
*dynamic* stop during retract, the reed gives *persistent* truth afterward.
|
||||
|
||||
## What it delivers (and what it doesn't)
|
||||
|
||||
- **Reliable CLOSED (stowed) detection.** Awnings extend to an arbitrary spot, so
|
||||
there's no meaningful "fully open" endpoint — but the fully-retracted position is
|
||||
hard and repeatable. That's the state that matters (don't drive off / don't let
|
||||
it flap): a single reed there answers *stowed vs. not*.
|
||||
- It does **not** measure extension %. If you ever want an "opening/closing"
|
||||
animation you already get that from the CAN motion byte; the reed just pins down
|
||||
the resting truth.
|
||||
|
||||
## Bill of materials (~$15–20)
|
||||
|
||||
| Part | Notes |
|
||||
|------|-------|
|
||||
| **ESP32-C3 SuperMini** (or Wemos D1 mini / ESP8266) | Tiny, WiFi, 3.3 V logic. C3 recommended (native ESP-IDF, cheap, plenty of GPIO). |
|
||||
| **Weatherproof reed switch** | RV-compartment / garage-door style, **potted + leaded**, normally-open. Get a wide-gap one (pull-in ≥ 15–20 mm) so alignment is forgiving. |
|
||||
| **Bar/block magnet** | Match/exceed the reed's rated gap. Rare-earth block for margin. |
|
||||
| **12 V → 5 V buck** (MP1584 / mini360 or an automotive USB buck) | Tap the awning motor's 12 V; always-on beats battery/deep-sleep for instant state and no maintenance. |
|
||||
| **Small IP65 enclosure + gland** | Mount the ESP + buck out of the weather. |
|
||||
| Fused 12 V tap (inline 1 A) | Protect the tap off the motor harness. |
|
||||
|
||||
## Wiring
|
||||
|
||||
```
|
||||
awning 12V harness --[inline 1A fuse]--> buck IN+ buck OUT+ (5V) --> ESP 5V
|
||||
chassis GND -----> buck IN- ----buck OUT- ------> ESP GND
|
||||
|
||||
reed leg A --> ESP GPIO4
|
||||
reed leg B --> ESP GND
|
||||
```
|
||||
|
||||
- Reed to GND with the **internal pull-up** enabled: pin idles HIGH (not stowed),
|
||||
goes LOW when the magnet is present (stowed). The ESPHome config below inverts
|
||||
that so the sensor reads ON = stowed.
|
||||
- No external resistor needed. An optional 0.1 µF across the reed helps debounce,
|
||||
but the software `delayed_on/off` below is enough.
|
||||
- Avoid the C3 strapping pins (GPIO2, 8, 9); GPIO4 is safe. GPIO8 has the onboard
|
||||
LED if you want a status blink.
|
||||
|
||||
## Mounting
|
||||
|
||||
- **Magnet on the moving part** (the lead rail / roller endcap that seats when
|
||||
stowed); **reed on the fixed part** (mounting rail or a bracket on the coach).
|
||||
- Aim for the magnet to land within the reed's pull-in gap when the awning is
|
||||
pulled in tight — the same "closed" position the current-stall stop lands on.
|
||||
Expect a test-fit: mark where the rail seats, mount, confirm the sensor flips.
|
||||
- Outdoor: use the potted reed, point the gland down, silicone the entry, and
|
||||
strain-relief the lead so awning motion doesn't fatigue it.
|
||||
|
||||
## ESPHome config
|
||||
|
||||
New device `awning-sensor` (mirror the conventions in `onecontrol-canbus.yaml` /
|
||||
`gazebo-fan-proxy.yaml`: `secrets.yaml` for WiFi + API key, OTA after first USB
|
||||
flash, fallback AP + captive portal). DHCP on `OmnissiahsReach`.
|
||||
|
||||
```yaml
|
||||
substitutions:
|
||||
name: awning-sensor
|
||||
friendly_name: Awning Sensor
|
||||
|
||||
esphome:
|
||||
name: ${name}
|
||||
friendly_name: ${friendly_name}
|
||||
|
||||
esp32:
|
||||
board: esp32-c3-devkitm-1
|
||||
framework:
|
||||
type: esp-idf
|
||||
|
||||
logger:
|
||||
api:
|
||||
encryption:
|
||||
key: !secret api_key
|
||||
ota:
|
||||
- platform: esphome
|
||||
|
||||
wifi:
|
||||
ssid: !secret wifi_ssid # OmnissiahsReach
|
||||
password: !secret wifi_password
|
||||
ap:
|
||||
ssid: "Awning-Sensor Fallback"
|
||||
password: !secret fallback_ap_password
|
||||
captive_portal:
|
||||
|
||||
binary_sensor:
|
||||
- platform: gpio
|
||||
name: "Awning Stowed"
|
||||
id: awning_stowed
|
||||
pin:
|
||||
number: GPIO4
|
||||
mode:
|
||||
input: true
|
||||
pullup: true
|
||||
inverted: true # reed->GND: magnet present = LOW = ON (stowed)
|
||||
filters:
|
||||
- delay_on: 200ms # debounce the rail seating
|
||||
- delay_off: 200ms
|
||||
# ON = awning pulled in tight (stowed / closed)
|
||||
# OFF = not stowed (extended, or mid-travel)
|
||||
```
|
||||
|
||||
`secrets.yaml` needs `wifi_ssid`, `wifi_password`, `fallback_ap_password`,
|
||||
`api_key` (generate with `esphome`). First flash over USB (`esphome run ... `),
|
||||
thereafter OTA — same as the other campsite nodes.
|
||||
|
||||
## HA integration
|
||||
|
||||
The reed is a separate device from the CAN node, so it lands as its own entity:
|
||||
|
||||
1. **Campsite Pi** auto-discovers it via the ESPHome integration →
|
||||
`binary_sensor.awning_sensor_awning_stowed` (rename to
|
||||
`binary_sensor.awning_stowed`). ON = stowed.
|
||||
2. **Bridge to home HA** — add to `/config/packages/mqtt_bridge.yaml` (repo:
|
||||
`canbus/ha/mqtt_bridge_onecontrol.yaml`) next to the other campsite entities:
|
||||
a discovery block (`homeassistant/binary_sensor/campsite/awning_stowed/config`,
|
||||
device `campsite_onecontrol`, `device_class: "opening"` reads on=open/off=closed,
|
||||
or leave classless for a plain stowed/clear), plus a state-forward trigger on
|
||||
`binary_sensor.awning_stowed` → `campsite/binary_sensor/awning_stowed/state`.
|
||||
Appears on home as `binary_sensor.campsite_onecontrol_awning_stowed`.
|
||||
3. Add the tile to home HA **Overview → Camper → OneControl** section.
|
||||
|
||||
### Optional: make the cover *truthful* (template cover)
|
||||
|
||||
Right now `cover.onecontrol_can_awning` is `assumed_state`. With the reed you can
|
||||
wrap it in a template cover on the Pi whose closed state is the *real* reed, while
|
||||
commands still hit the CAN cover:
|
||||
|
||||
```yaml
|
||||
cover:
|
||||
- platform: template
|
||||
covers:
|
||||
awning_true:
|
||||
friendly_name: "Awning"
|
||||
device_class: awning
|
||||
value_template: "{{ 'closed' if is_state('binary_sensor.awning_stowed','on') else 'open' }}"
|
||||
close_cover:
|
||||
- action: cover.close_cover # -> CAN cover auto-retract
|
||||
target: { entity_id: cover.onecontrol_can_awning }
|
||||
stop_cover:
|
||||
- action: cover.stop_cover
|
||||
target: { entity_id: cover.onecontrol_can_awning }
|
||||
```
|
||||
|
||||
Bridge `cover.awning_true` to home instead of the raw CAN cover, and you get a
|
||||
cover that shows genuine open/closed. (Keep `payload_open` disabled as today.)
|
||||
|
||||
### Automations this unlocks
|
||||
|
||||
- **Left-it-out alarm:** awning `not stowed` + (leaving geofence / wind gust > X /
|
||||
rain) → Discord ping, or auto-fire `cover.close_cover`.
|
||||
- **Confirm the retract actually seated:** after an auto-retract, if the current
|
||||
stall fired but the reed is still OFF a few seconds later → alert (mis-seat).
|
||||
|
||||
> **Option-1 limitation:** because the reed is on a *separate* device from the CAN
|
||||
> node, the auto-retract's stall gate can't consume it on-device — any
|
||||
> reed↔retract logic is a cross-device HA automation, not firmware. If you want
|
||||
> the ESP to stop the motor *on the reed itself* (belt-and-suspenders with the
|
||||
> current stall), that's Option 2 (wire the reed to a spare GPIO on the CAN node
|
||||
> `192.168.69.18`; the cover entity then reads it directly and becomes truthful
|
||||
> with no template cover).
|
||||
|
||||
## Touchpoints checklist (campsite ESPHome node)
|
||||
|
||||
- [ ] `secrets.yaml` (WiFi = OmnissiahsReach, API key, fallback AP pw)
|
||||
- [ ] USB flash once, confirm on `OmnissiahsReach` (DHCP `192.168.69.x`); OTA after
|
||||
- [ ] Adopt in campsite Pi HA (ESPHome integration), rename entity
|
||||
- [ ] Mount reed + magnet, verify it flips exactly at the stowed position
|
||||
- [ ] `mqtt_bridge.yaml`: discovery + state-forward → home HA; add dashboard tile
|
||||
- [ ] (optional) template cover `awning_true`; bridge it instead of the raw cover
|
||||
- [ ] (optional) automations: left-out alarm, retract-seat confirmation
|
||||
|
||||
## Validation
|
||||
|
||||
1. USB-flash, join WiFi, adopt in HA. Toggle by hand with a magnet → `awning_stowed`
|
||||
flips ON/OFF with the 200 ms debounce.
|
||||
2. Mount, retract via the dashboard (auto-retract): at full stow the reed should go
|
||||
ON right around when the current-stall stop fires.
|
||||
3. Extend at the OEM wall switch → reed OFF. Confirm home HA mirrors it.
|
||||
Reference in New Issue
Block a user