lippert-onecontrol/canbus/awning-closed-sensor-spec.md

# 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.