From 9a8e7986dc2356b6e4e66eb61a60d8637141eded Mon Sep 17 00:00:00 2001 From: Otto Winter Date: Wed, 13 Mar 2019 16:17:05 +0100 Subject: [PATCH] Add docs --- components/binary_sensor/index.rst | 5 + components/esp32_camera.rst | 109 ++++++++++++++++++++ components/light/partition.rst | 1 + components/servo.rst | 160 +++++++++++++++++++++++++++++ components/stepper/index.rst | 74 +++++++++++++ guides/automations.rst | 2 + images/camera.svg | 1 + images/servo.svg | 1 + index.rst | 2 + 9 files changed, 355 insertions(+) create mode 100644 components/esp32_camera.rst create mode 100644 components/servo.rst create mode 100644 images/camera.svg create mode 100644 images/servo.svg diff --git a/components/binary_sensor/index.rst b/components/binary_sensor/index.rst index 9a79a7ff2..b485f41bf 100644 --- a/components/binary_sensor/index.rst +++ b/components/binary_sensor/index.rst @@ -300,6 +300,11 @@ This :ref:`Condition ` checks if the given binary sensor is ON # Same syntax for is_off binary_sensor.is_on: my_binary_sensor + # With duration, true if has been on for at least 5s + binary_sensor.is_on: + id: my_binary_sensor + for: 5s + lambda calls ************ diff --git a/components/esp32_camera.rst b/components/esp32_camera.rst new file mode 100644 index 000000000..5db1f9bd3 --- /dev/null +++ b/components/esp32_camera.rst @@ -0,0 +1,109 @@ +ESP32 Camera Component +====================== + +.. seo:: + :description: Instructions for setting up the ESP32 Cameras in ESPHome + :image: camera.png + +The ``esp32_camera`` component allows you to use ESP32-based camera boards in ESPHome that +directly integrate into Home Assistant through the native API. + +.. warning:: + + Some ESP32 Camera boards have insufficient cooling and will overheat over time, + ESPHome does only activate the camera when Home Assistant requests an image, but + the camera until can still heat up considerably for some boards. + + If the camera is not recognized after a reboot and the unit feels warm, try waiting for + it to cool down and check again - if that still doesn't work try enabling the test pattern. + +.. note:: + + The example configuration is valid for M5Stack ESP32 camera models. + +.. code-block:: yaml + + # Example configuration entry + esp32_camera: + name: My Camera + external_clock: + pin: GPIO27 + frequency: 20MHz + i2c_pins: + sda: GPIO25 + scl: GPIO23 + data_pins: [GPIO17, GPIO35, GPIO34, GPIO5, GPIO39, GPIO18, GPIO36, GPIO19] + vsync_pin: GPIO22 + href_pin: GPIO26 + pixel_clock_pin: GPIO21 + reset_pin: GPIO15 + resolution: 640x480 + jpeg_quality: 10 + +Configuration variables: +------------------------ + +- **name** (**Required**, string): The name of the camera. + +Connection Options: + +- **data_pins** (**Required**, list of pins): The data lanes of the camera, this must be a list + of 8 gpio pins. +- **vsync_pin** (**Required**, pin): The pin the VSYNC line of the camera is connected to. +- **href_pin** (**Required**, pin): The pin the HREF line of the camera is connected to. +- **pixel_clock_pin** (**Required**, pin): The pin the pixel clock line of the camera is connected to. +- **external_clock** (**Required**): The configuration of the external clock to drive the camera. + + - **pin** (**Required**, pin): The pin the external clock line is connected to. + - **frequency** (*Optional*, float): The frequency of the external clock, must be either 20MHz + or 10MHz. Defaults to ``20MHz``. + +- **i2c_pins** (**Required**): The i2c control pins of the camera. + + - **sda** (**Required**, pin): The SDA pin of the i2c interface. + - **scl** (**Required**, pin): The SCL pin of the i2c interface. + +- **reset_pin** (*Optional*, pin): The ESP pin the reset pin of the camera is connected to. + If set, this will reset the camera before the ESP boots. +- **power_down_pin** (*Optional*, pin): The ESP pin to power down the camera. + If set, this will power down the camera while it is inactive. +- **test_pattern** (*Optional*, boolean): When enabled, the camera will show a test pattern + that can be used to debug connection issues. + +Frame Settings: + +- **max_framerate** (*Optional*, float): The maximum framerate the camera will generate images at. + Up to 60Hz is possible (with reduced frame sizes), but beware of overheating. Defaults to ``10 fps``. +- **idle_framerate** (*Optional*, float): The framerate to capture images at when no client + is requesting a full stream. Defaults to ``0.1 fps``. +- **resolution** (*Optional*, enum): The resolution the camera will capture images at. Higher + resolutions require more memory, if there's not enough memory you will see an error during startup. + + - ``160x120`` (QQVGA) + - ``128x160`` (QQVGA2) + - ``176x144`` (QCIF) + - ``240x176`` (HQVGA) + - ``320x240`` (QVGA) + - ``400x296`` (CIF) + - ``640x480`` (VGA, default) + - ``800x600`` (SVGA) + - ``1024x768`` (XGA) + - ``1280x1024`` (SXGA) + - ``1600x1200`` (UXGA) + +- **jpeg_quality** (*Optional*, int): The JPEG quality that the camera should encode images with. + From 10 to 63. Defaults to ``10``. + +- **contrast** (*Optional*, int): The contrast to apply to the picture, from -2 to 2. Defaults to ``0``. +- **brightness** (*Optional*, int): The brightness to apply to the picture, from -2 to 2. Defaults to ``0``. +- **saturation** (*Optional*, int): The saturation to apply to the picture, from -2 to 2. Defaults to ``0``. +- **vertical_flip** (*Optional*, bool): Whether to flip the image vertically. Defaults to ``true``. +- **horizontal_mirror** (*Optional*, bool): Whether to mirror the image horizontally. Defaults to ``true``. + +See Also +-------- + +- :apiref:`wifi_component.h` +- :ghedit:`Edit` + +.. disqus:: diff --git a/components/light/partition.rst b/components/light/partition.rst index 00ed09381..3c96fa899 100644 --- a/components/light/partition.rst +++ b/components/light/partition.rst @@ -10,6 +10,7 @@ The ``partition`` light platform allows you to combine multiple addressable ligh This platform also allows splitting up an addressable lights into multiple segments, so that segments can be individually controlled. +Similarly, a single light strip can be partitioned into multiple partitions with this integration. .. code-block:: yaml diff --git a/components/servo.rst b/components/servo.rst new file mode 100644 index 000000000..50a291985 --- /dev/null +++ b/components/servo.rst @@ -0,0 +1,160 @@ +Servo Component +=============== + +.. seo:: + :description: Instructions for setting up servos in ESPHome + :image: servo.png + +The ``servo`` component allows you to use servo motors with ESPHome. Servos are +motor controllers that contain all the electronics necessary for driving the motor and provide +a simple PWM interface to control the motor. + +This integration works with both continuous-rotation and absolute servos and has a similar +interface to the Arduino Servo library. + +First, create an :ref:`output component ` (here ``esp8266_pwm``) for the pin the +servo is connected to. Then connect that output to the servo component by assigning an ID. +Please note the frequency of the output must be around 50Hz, as most servo controllers +only operate in this frequency range. + +.. note:: + + This component will not show up in the Home Assistant front-end automatically because + Home Assistant doesn't have support for servos. Please see :ref:`servo-ha-config`. + +.. code-block:: yaml + + # Example configuration entry + servo: + - id: my_servo + output: pwm_output + + # Example output platform + output: + - platform: esp8266_pwm + id: pwm_output + pin: D1 + frequency: 50 Hz + +Configuration variables: +------------------------ + +- **output** (**Required**, :ref:`config-id`): The ID of the output component to use for this servo. +- **id** (**Required**, :ref:`config-id`): The ID of this servo so that it can be controlled. + +Advanced Options: + +- **min_level** (*Optional*, percentage): The PWM duty cycle the minimum value (-100%) will map + to. Defaults to ``3%``. +- **idle_level** (*Optional*, percentage): The PWM duty cycle the idle value (0%) will map + to. This is also the state of the servo at startup. Defaults to ``7.5%``. +- **max_level** (*Optional*, percentage): The PWM duty cycle the maximum value (100%) will map + to. Defaults to ``12.0%``. + +.. _servo-write_action: + +``servo.write`` Action +---------------------- + +To use your servo motor in :ref:`automations ` or templates, you can use this action to set the +target level of the servo from -100% to 100%. + +- -100% (= -1.0) is the minimum value of the servo. For continuous-rotation servos this will + rotate the servo backward. +- 0% (= 0.0) is the idle level of the servo. For continuous-rotation servos this will + stop the servo. +- 100% (= 1.0) is the maximum value of the servo. For continuous-rotation servos this will + rotate the servo forward. + +.. code-block:: yaml + + on_...: + then: + - servo.write: + id: my_servo + level: -100.0% + + # Templated + - servo.write: + id: my_servo + # For template values, range is [-1; 1] + level: !lambda |- + if (id(my_binary_sensor).state) { + return 1.0; + } else { + return -1.0; + } + +Configuration options: + +- **id** (**Required**, :ref:`config-id`): The ID of the servo. +- **level** (*Optional*, percentage, :ref:`templatable `): The target level. + Range is from -100% to 100% (-1.0 to 1.0). + +.. note:: + + This action can also be expressed as a :ref:`lambda `: + + .. code-block:: cpp + + id(my_servo).write(1.0); + +.. _servo-ha-config: + +Home Assistant Configuration +---------------------------- + +This component will not show up in the Home Assistant frontend automatically because Home Assistant +does not support servos 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 servo from the frontend. + +.. code-block:: yaml + + # Home Assistant configuration + input_number: + servo_control: + name: Servo Control + initial: 0 + min: -100 + max: 100 + step: 1 + mode: slider + + automation: + - alias: Write Servo Value to ESP + trigger: + platform: state + entity_id: input_number.servo_control + action: + # Replace livingroom with the name you gave the ESP + - service: esphome.livingroom_control_servo + data_template: + target: '{{ trigger.to_state.state | int }}' + +.. code-block:: yaml + + # ESPHome configuration + api: + services: + - service: control_servo + variables: + level: float + then: + - servo.write: + id: my_servo + level: !lambda 'return level / 100.0;' + + servo: + - platform: ... + # [...] servo config + id: my_servo + + +See Also +-------- + +- :apiref:`servo.h` +- :ghedit:`Edit` + +.. disqus:: diff --git a/components/stepper/index.rst b/components/stepper/index.rst index 56aac90d1..9240e3e60 100644 --- a/components/stepper/index.rst +++ b/components/stepper/index.rst @@ -11,6 +11,11 @@ Currently only the A4988 stepper driver (`datasheet `__) and ULN2003 (`datasheet `__) are supported. +.. note:: + + This component will not show up in the Home Assistant front-end automatically because + Home Assistant doesn't have support for steppers. Please see :ref:`stepper-ha-config`. + A4988 Configuration ------------------- @@ -133,6 +138,23 @@ Configuration options: - **id** (**Required**, :ref:`config-id`): The ID of the stepper. - **target** (*Optional*, int, :ref:`templatable `): The target position in steps. +.. warning:: + + This turns the stepper to an absolute position! To have the servo move *relative* to the current + position, first reset the current position and then set the target to the relative value. + + .. code-block:: yaml + + on_...: + then: + # Move 150 steps forward + - stepper.report_position: + id: my_stepper + position: 0 + - stepper:set_target: + id: my_stepper + target: 150 + .. note:: This action can also be expressed as a :ref:`lambda `: @@ -195,6 +217,58 @@ Configuration options: // Get the current position: int pos = id(my_stepper).current_position; +.. _stepper-ha-config: + +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. + +.. code-block:: yaml + + # Home Assistant configuration + input_number: + stepper_control: + name: Stepper Control + initial: 0 + min: -1000 + max: 1000 + step: 1 + mode: slider + + automation: + - alias: Write Stepper Value to ESP + trigger: + platform: state + entity_id: input_number.stepper_control + action: + # Replace livingroom with the name you gave the ESP + - service: esphome.livingroom_control_stepper + data_template: + target: '{{ trigger.to_state.state | int }}' + +.. code-block:: yaml + + # ESPHome configuration + api: + services: + - service: control_stepper + variables: + target: int + then: + - stepper.set_target: + id: my_stepper + target: !lambda 'return target;' + + stepper: + - platform: ... + # [...] stepper config + id: my_stepper + + See Also -------- diff --git a/guides/automations.rst b/guides/automations.rst index 9bf0076ad..b12fc8c23 100644 --- a/guides/automations.rst +++ b/guides/automations.rst @@ -343,6 +343,8 @@ All Actions - :ref:`sensor.template.publish ` / :ref:`binary_sensor.template.publish ` / :ref:`cover.template.publish ` / :ref:`switch.template.publish ` / :ref:`text_sensor.template.publish ` +- :ref:`stepper.set_target ` / :ref:`stepper.report_position ` +- :ref:`servo.write ` .. _config-condition: diff --git a/images/camera.svg b/images/camera.svg new file mode 100644 index 000000000..b967fd69f --- /dev/null +++ b/images/camera.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/images/servo.svg b/images/servo.svg new file mode 100644 index 000000000..9e0ebb149 --- /dev/null +++ b/images/servo.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/index.rst b/index.rst index 4ede57667..2cd0f8d32 100644 --- a/index.rst +++ b/index.rst @@ -261,7 +261,9 @@ Misc Components Status LED, components/status_led, led-on.svg Time, components/time, clock-outline.svg Stepper, components/stepper/index, stepper.svg + Servo, components/servo, servo.svg ESP32 Ethernet, components/ethernet, ethernet.svg + ESP32 Camera, components/esp32_camera, camera.svg Additional Custom Components ----------------------------