More descriptive information for noobs (#658)

* More descriptive information for noobs

The original doc was fairly bare and has led to some confusion, especially around naming and other "magic".  I've added more description to make this easier to understand.

* Minor changes

* Update formatting

Co-authored-by: Fabian Affolter <mail@fabian-affolter.ch>

components/stepper/index.rst

@@ -19,9 +19,10 @@ and ULN2003 (`datasheet <http://www.ti.com/lit/ds/symlink/uln2003a.pdf>`__) are
 A4988 Configuration
 -------------------
 
+Put this code into the configuration file on ESPhome for this device.
+
 .. code-block:: yaml
 
-    # Example configuration entry
     stepper:
       - platform: a4988
         id: my_stepper
@@ -69,6 +70,8 @@ Configuration variables:
 ULN2003 Configuration
 ---------------------
 
+Put this code into the configuration file on ESPHome for this device.
+
 .. code-block:: yaml
 
     # Example configuration entry
@@ -103,7 +106,9 @@ Configuration variables:
   stepper at. Note most steppers can't step properly with speeds higher than 250 steps/s.
 - **acceleration** (*Optional*, float): The acceleration in ``steps/s^2`` (steps per seconds squared)
   to use when starting to move. The default is ``inf`` which means infinite acceleration, so the
-  stepper will try to drive with the full speed immediately.
+  stepper will try to drive with the full speed immediately.  This value is helpful if that first motion of 
+  the motor is too jerky for what it's moving.  If you make this a small number, it will take the motor a 
+  moment to get up  to speed.
 - **deceleration** (*Optional*, float): The same as ``acceleration``, but for when the motor is decelerating
   shortly before reaching the set position. Defaults to ``inf`` (immediate deceleration).
 
@@ -220,14 +225,15 @@ Configuration variables:
 Home Assistant Configuration
 ----------------------------
 
-This component will not show up in the Home Assistant frontend automatically because Home Assistant
-does not support steppers natively (raise this issue in Home Assistant forums to make this a
-higher priority for Home Assistant). You can add this to your Home Assistant configuration to
-be able to control the stepper from the frontend.
+This component will not show up in the Home Assistant front-end (Overview) automatically because 
+Home Assistant does not support steppers natively.
+
+You can add the stepper component code below to your Home Assistant configuration (``configuration.yaml``) to
+be able to control the stepper from the front-end. 
 
 .. code-block:: yaml
 
-    # Home Assistant configuration
+    # Add a slider control to Home Assistant to set an integer value
     input_number:
       stepper_control:
         name: Stepper Control
@@ -236,7 +242,8 @@ be able to control the stepper from the frontend.
         max: 1000
         step: 1
         mode: slider
-
+    
+    # Do something when the slider changes
     automation:
       - alias: Write Stepper Value to ESP
         trigger:
@@ -248,6 +255,40 @@ be able to control the stepper from the frontend.
             data_template:
               target: '{{ trigger.to_state.state | int }}'
 
+In the above code, "stepper_control" is the ID of a numeric input field. It must be unique and it is 
+used in the automation section as a reference name. The display name for this field is in 
+stepper_control's ``name`` key.  
+
+If you want your user interface to give you more control over your stepper controller, such as 
+setting the acceleration, deceleration, etc, then you can add more input fields after ``stepper_control``
+but before ``automation``. They can be a simple number-entry field (mode: box) or a slider like this.
+Each of these extra input fields needs an associated input parameter defined on the ESPHome device's
+API service.
+
+The automation section tells Home Assistant what to do when the slider changes. It needs a trigger
+(state of the ``stepper_control`` slider) and an action. In the trigger section, ``entity_id`` must refer 
+back to the configuration ID that triggers the automation. For us, that is the ``stepper_control``
+field in the ``input_number`` item. That's why the value is ``input_number.stepper_control``.
+
+In the action section, the service name is vital to get right: it's the glue that connects Home Automation's
+front-end to the ESPHome device configuration. While you might expect the syntax to be ``esphome.<your_device>.<api_service>``,
+the correct syntax is to join the device ID to the API service ID with an underscore,
+as in ``esphome.livingroom_control_stepper`` where "Livingroom" is a device in ESPHome and "control_stepper" is an
+API service for that device.
+
+The template string is used to get the "state" value from the ``target`` field (defined in the target section) on the 
+``input_number`` component of the Home Assistant front-end. This value is then passed to the API service as defined in
+the ESPHome device's configuration. The ``data_template`` section lists one value for each of the input parameters on
+the service being called by the automation. In our case, the ESPHome device has an API service with a single parameter,
+"target". If you called this "my_target", then the last line above should be ``my_target: '{{ trigger.to_state.state | int }}'``.
+Getting this linkage right is very important.
+
+The following code needs to go in the ESPHome configuration file for this device. Above, we mention "API service"
+a lot. This code is where that is defined. You may have already added it (or something similar). Note
+that the input variable for the ``control_stepper`` service is called ``target``. That's what matches with the 
+automation configuration above. Also note that the variable ``target`` is defined as an integer. That means it
+must be an integer number, not a string.
+
 .. code-block:: yaml
 
     # ESPHome configuration