Merge pull request #31 from Valar-Systems/fix/motor-direction-persist

fix(firmware): persist Motor Direction across power loss; show as a dropdown

Author: daniel-frenkel

docs/Ropener-User-Guide.md

@@ -1,6 +1,6 @@
 # Ropener Curtain Controller — User Guide
 
-*Firmware 2.6.1*
+*Firmware 2.6.3*
 
 ---
 
@@ -261,7 +261,7 @@ These settings are optional. The defaults work for a typical installation; chang
 | Centimeters | Total travel distance of the curtain, in cm. | Set this to your curtain's open-to-closed travel. Default 30 cm. |
 | Speed | How fast the motor runs (steps/second). | Higher is faster but louder. Effective max is 2000. |
 | Acceleration | How quickly the motor speeds up / slows down. | Higher is snappier; too high can skip or be noisy. |
-| Motor Direction | Which way the motor winds the rope. | Flip this if Open and Close are reversed for your install. |
+| Motor Direction | Which way the motor winds the rope (**Normal** / **Reversed ↺**). | Set to **Reversed** if Open and Close are backwards for your install. Your choice is saved and survives a power loss. |
 | IRUN value | Motor running current / torque (1–31). | Raise for more pulling force; lower if the driver runs hot. Default 25. |
 | SGTHRS value | Sensitivity of the stall detection used for homing (0–255). | See tuning note below. |
 | TCOOLTHRS value | Speed threshold above which stall detection is active. | See tuning note below. |
@@ -293,7 +293,7 @@ When first added, Home Assistant may warn that communication is not encrypted. T
 | --- | --- |
 | Can't find the web page | Make sure your phone/PC is on the same Wi-Fi as the device. Try the device's IP address instead of the `.local` name. Confirm it joined Wi-Fi (the setup hotspot should be gone). |
 | No setup hotspot appears | Wait a full minute after power-on. If it already joined a network, hold Button 3 for 3–10 seconds to reset Wi-Fi and try again. |
-| Open/Close are reversed | Toggle the “Motor Direction” switch. |
+| Open/Close are reversed | Set the “Motor Direction” setting to **Reversed**. |
 | Position is wrong / drifted | Run homing (Section 5) to recalibrate. |
 | Schedule fires at the wrong time | Check the Timezone value (Section 7/8) and that the device has internet for time sync. |
 | Schedule doesn't run | Confirm “Schedule Enabled” is ON and that Open/Close times are set. |

docs/wiki-Firmware-Guide.md

@@ -53,7 +53,7 @@ At a high level, the curtain hardware is an **ESP32** microcontroller driving a
 | `ota:` | Over-the-air update support, so later updates don't need a USB cable. |
 | `stepper:` + `cover:` | The motion engine. Position is tracked in motor *steps* and reported to the UI as a 0–1 (closed→open) ratio. |
 | `binary_sensor:` (buttons) | The three physical buttons (close/home, open, Wi-Fi reset). |
-| `number:` / `switch:` / `text:` / `datetime:` | The runtime-tunable settings — travel distance, speed, motor direction, schedule times, timezone, latitude/longitude, StallGuard thresholds. |
+| `number:` / `select:` / `switch:` / `text:` / `datetime:` | The runtime-tunable settings — travel distance, speed, motor direction, schedule times, timezone, latitude/longitude, StallGuard thresholds. |
 | `time:` + `sun:` + `interval:` | The daily schedule, including the optional sunrise/sunset mode. |
 
 You don't need to understand every line to update the firmware — but it's all commented in the file itself if you want to dig in.

…rmware/VAL3000/Ropener-VAL3000-2.6.2.yml …rmware/VAL3000/Ropener-VAL3000-2.6.3.ymlfirmware/VAL3000/Ropener-VAL3000-2.6.2.yml renamed to firmware/VAL3000/Ropener-VAL3000-2.6.3.yml firmware/VAL3000/Ropener-VAL3000-2.6.2.yml renamed to firmware/VAL3000/Ropener-VAL3000-2.6.3.yml

@@ -150,8 +150,8 @@ external_components:
 # Persistent state
 # -----------------------------------------------------------------------------
 # All globals use restore_value so settings survive reboots. They are mirrored
-# by `number` / `switch` entities further down — editing in Home Assistant
-# updates the global AND pushes the value to the appropriate TMC2209 register.
+# by `number` / `select` / `switch` entities further down — editing in Home
+# Assistant updates the global AND pushes the value to the TMC2209 / stepper.
 globals:
   # Motor run current (TMC2209 IRUN field, 0-31). Higher = more torque + heat.
   # 25 is a moderate setting; reduce if the driver overheats or skips cooldown.
@@ -206,7 +206,8 @@ globals:
     initial_value: '12732'
 
   # Motor shaft direction. Persisted so the unit comes up the same way after
-  # a reboot. Toggled by the "Motor Direction" switch entity.
+  # a reboot. Set by the "Motor Direction" select entity, which mirrors this
+  # global rather than holding its own state (see the select for why).
   - id: global_stepper_direction
     type: esphome::tmc2209::ShaftDirection
     restore_value: yes
@@ -481,7 +482,7 @@ substitutions:
 
   # Firmware version — single source of truth. Feeds project.version (below) and
   # the "Firmware Version" diagnostic sensor shown on the web UI / in HA.
-  firmware_version: "2.6.2"
+  firmware_version: "2.6.3"
 
   # NOTE: board-specific substitutions — board_variant, board_id, the GPIO pin
   # map (pin_uart_tx/rx, pin_enn/index/diag, pin_btn1/btn2/btn_wifi) and
@@ -1192,34 +1193,71 @@ button:
 
 
 # -----------------------------------------------------------------------------
-# Configuration switches
+# Configuration selects
 # -----------------------------------------------------------------------------
-# Motor Direction: flips the shaft direction so the same close/open commands
-# wind the rope the right way regardless of how the motor was mounted.
-#   OFF -> CLOCKWISE
-#   ON  -> COUNTERCLOCKWISE
-# `optimistic: true` is fine here because the action is idempotent and we
-# persist the truth in `global_stepper_direction`.
-switch:
+# Motor Direction: picks the shaft direction so the same close/open commands
+# wind the rope the right way regardless of how the motor was mounted. The value
+# is just the motor's physical spin direction; flipping it reverses open and
+# close together. Labelled by OUTCOME rather than CW/CCW, because "clockwise" has
+# no defined viewpoint here (front vs. spindle side) and doesn't single out open
+# or close on its own:
+#   "Normal"     -> CLOCKWISE          (default; open/close as-is)
+#   "Reversed ↺" -> COUNTERCLOCKWISE   (pick this if open and close are backwards)
+#
+# This entity is a pure MIRROR of `global_stepper_direction`, exactly like the
+# number entities mirror their globals: `lambda` reports the current option from
+# the global, and `set_action` writes the global + pushes the new direction to
+# the driver. The global (restore_value: yes) is the single source of truth and
+# is applied to the driver in on_boot.
+#
+# Crucially this select carries NO optimistic/restore state of its own, so it
+# never writes the global at startup. That startup write is precisely what the
+# old "Motor Direction" *switch* did wrong: a template switch defaults to an
+# ALWAYS_OFF restore, so every power cycle re-ran its turn_off_action and reset
+# the restored direction back to CLOCKWISE. Mirroring the global instead removes
+# that second source of truth.
+#
+# set_action ALSO flushes the change to flash immediately. ESPHome batches
+# preference writes (default flash_write_interval 60s) and does not flush on an
+# abrupt power loss, so a global.set alone can be lost if the user changes the
+# direction and pulls power within that window — exactly what happens while
+# mounting/testing. update() pushes the changed global into the pending-save
+# buffer; global_preferences->sync() writes it to NVS right away. The 60s batch
+# is left intact for everything else, so the 200 ms position writes during
+# motion don't hammer flash.
+select:
   - platform: template
     name: "Motor Direction"
     web_server:
       sorting_weight: 2
       sorting_group_id: group_setup
     entity_category: CONFIG
-    optimistic: true
-    turn_on_action:
-      - globals.set:
-          id: global_stepper_direction
-          value: 'esphome::tmc2209::ShaftDirection::COUNTERCLOCKWISE'
-      - tmc2209.configure:
-          direction: !lambda return id(global_stepper_direction);
-    turn_off_action:
-      - globals.set:
-          id: global_stepper_direction
-          value: 'esphome::tmc2209::ShaftDirection::CLOCKWISE'
+    update_interval: 1s
+    options:
+      - "Normal"
+      - "Reversed ↺"
+    lambda: |-
+      if (id(global_stepper_direction) == esphome::tmc2209::ShaftDirection::COUNTERCLOCKWISE)
+        return std::string("Reversed ↺");
+      return std::string("Normal");
+    set_action:
+      - lambda: |-
+          id(global_stepper_direction) = (x.find("Reversed") != std::string::npos)
+            ? esphome::tmc2209::ShaftDirection::COUNTERCLOCKWISE
+            : esphome::tmc2209::ShaftDirection::CLOCKWISE;
       - tmc2209.configure:
           direction: !lambda return id(global_stepper_direction);
+      - lambda: |-
+          // Persist immediately (see the note above the select). update() moves
+          // the changed value into the pending-save buffer; sync() flushes that
+          // buffer to NVS now, so the choice survives an unplug seconds later.
+          global_stepper_direction->update();
+          global_preferences->sync();
+
+# -----------------------------------------------------------------------------
+# Configuration switches
+# -----------------------------------------------------------------------------
+switch:
 
   # Schedule Enabled: master on/off for the daily schedule. When OFF, neither
   # schedule moves the cover. When ON, the "Sun Schedule" switch below selects