docs: project documentation + README v1.3.0 update

README.md

@@ -127,3 +127,100 @@ To enter pairing mode, refer to your specific remote control or timer switch man
 
 > [!NOTE]
 > The pairing instructions above are based on common Schellenberg products. Your specific device may have different procedures - always refer to the device's original manual if unsure.
+
+---
+
+## Motor Types: Bidirectional vs Timed (Non-Bidirectional)
+
+As of v1.3.0, the integration distinguishes between two motor types:
+
+| Type | Description |
+|------|-------------|
+| **Bidirectional** | Motor sends movement events back to the stick. The integration detects when motion starts and stops — this is the classic mode. All previously paired motors are treated as bidirectional by default. |
+| **Timed (non-bidirectional)** | Motor gives no movement feedback. The integration cannot detect when the motor starts or stops moving, so it times runs by measuring the wall-clock duration between button presses instead of waiting for events. |
+
+You select the motor type once, when adding the device. A timed motor requires a separate calibration flow (described below); a bidirectional motor uses the event-based flow documented in [Step 5: Calibrate your blinds](#step-5-calibrate-your-blinds).
+
+> [!NOTE]
+> Legacy subentries created before v1.3.0 have no mode flag and are treated as bidirectional — existing paired motors are unaffected.
+
+---
+
+## Adding an Already-Paired Motor Manually
+
+If a motor is already paired (for example it responds to an existing Schellenberg remote) you can add it to Home Assistant without triggering the radio-pairing procedure:
+
+1. In Home Assistant, go to **Settings > Devices & Services**.
+2. Find the **Schellenberg USB** integration and click on it.
+3. Click the **+** button to add a device.
+4. When the menu appears, choose **Add manually**.
+5. Enter the motor's **device enum** — a two-character hex value (e.g. `10`, `11`, `1A`) that identifies the device on the radio bus.
+6. Choose the **motor mode**: toggle on for bidirectional, toggle off for timed/non-bidirectional.
+7. Optionally provide a friendly name (defaults to `Blind <enum>` if left blank).
+8. For **timed motors only**: a second screen asks for the **initial position** (0–100 %). Set this to the motor's current physical position so the integration starts tracking from the right point. Use 100 % if the shutter is currently fully open.
+9. Click **Submit** — the device is created immediately with no radio-pairing step.
+
+> [!TIP]
+> The device enum is the two-hex-character address the stick uses to address the motor. If you are unsure of the value, check your previous pairing records or consult the integration logs — each enrolled device is logged with its enum at startup.
+
+---
+
+## Timed Calibration (for Non-Bidirectional Motors)
+
+> [!IMPORTANT]
+> This section describes the **timed calibration flow** for non-bidirectional (timed) motors. It is separate from and additional to the event-based "Calibration Steps" in [Step 5](#step-5-calibrate-your-blinds), which applies only to bidirectional motors. Do not use the event-based flow for a timed motor — it will wait indefinitely for movement events that never arrive.
+
+Because timed motors send no movement feedback, calibration is driven entirely by button presses: the integration sends a command, you watch the shutter move, and you press a button when it stops.
+
+#### Prerequisites
+
+- The shutter must be **fully open** (all the way up) before you start. If it is not, drive it to the top using your physical remote first.
+
+#### Starting Timed Calibration
+
+Access timed calibration the same way as regular calibration:
+
+- **After adding a timed motor**: the timed calibration flow launches automatically once the device is created.
+- **Later, from the device page**: click the **Calibrate** gear icon (⚙️) on the device page.
+
+#### Timed Calibration Steps
+
+1. **Precondition check**: Confirm the shutter is fully open. Press **Next** when ready — no command is sent at this point.
+
+2. **Close run**:
+   - The integration sends a **close** command to the motor.
+   - Watch the shutter travel all the way down to its physical endstop. Wait until it has fully stopped.
+   - Press **Next** to record the elapsed time.
+   - The integration does **not** send a stop command — the motor coasts to its physical endstop naturally.
+
+3. **Open run**:
+   - The integration sends an **open** command to the motor.
+   - Watch the shutter travel all the way up. Wait until it has fully stopped at the top endstop.
+   - Press **Next** to record the elapsed time.
+   - Again, no stop command is sent — the motor stops at its physical endstop.
+
+4. **Confirm**: The integration shows the measured close time and open time. Press **Done** to save, or check **Redo** to discard the measurements and start again from the precondition step.
+
+#### Guard Limits
+
+The integration validates each run before accepting it:
+
+| Condition | Guard | What to do |
+|-----------|-------|------------|
+| You pressed Next in under **2 seconds** | Rejected (likely a double-press or misfire) | The form re-shows; drive the shutter back to fully open manually and retry |
+| You waited more than **120 seconds** | Rejected ("walked away" run) | The form re-shows; drive the shutter back to fully open manually and retry |
+
+> [!IMPORTANT]
+> After a guard error, the shutter position is unknown — it may have stopped mid-travel. Return the shutter to the **fully open** position using your physical remote before pressing Next again.
+
+---
+
+## Driving a Timed Motor to a Position
+
+Once a timed motor has been calibrated, the position slider in the Home Assistant UI becomes active. Requesting a percentage (e.g., 50 %) causes the integration to:
+
+1. Determine the direction of travel (open or close) from the current tracked position.
+2. Send the appropriate command to the motor.
+3. Schedule a stop command after the computed fraction of the full-travel time has elapsed.
+
+The integration tracks position by dead-reckoning — it uses the calibrated open and close times to estimate where the shutter is. If the motor is ever moved outside of Home Assistant (e.g., by a physical remote), the tracked position will drift until the next full-travel recalibration.