Upstream
/
esphome-docs
mirror of https://github.com/esphome/esphome-docs.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Add docs

This commit is contained in:
Otto Winter 2019-03-13 16:17:05 +01:00
parent 29644fca3b
commit 9a8e7986dc
No known key found for this signature in database
GPG Key ID: DB66C0BE6013F97E
9 changed files with 355 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
components/binary_sensor/index.rst
View File

@ -300,6 +300,11 @@ This :ref:`Condition <config-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
************

109
components/esp32_camera.rst Normal file
View File

@ -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::

1
components/light/partition.rst
View File

@ -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

160
components/servo.rst Normal file
View File

@ -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 <output>` (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 <automation>` 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 <config-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 <config-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::

74
components/stepper/index.rst
View File

@ -11,6 +11,11 @@ Currently only the A4988 stepper driver
(`datasheet <https://www.pololu.com/file/0J450/a4988_DMOS_microstepping_driver_with_translator.pdf>`__)
and ULN2003 (`datasheet <http://www.ti.com/lit/ds/symlink/uln2003a.pdf>`__) 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 <config-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 <config-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
--------

2
guides/automations.rst
View File

@ -343,6 +343,8 @@ All Actions
- :ref:`sensor.template.publish <sensor-template-publish_action>` / :ref:`binary_sensor.template.publish <binary_sensor-template-publish_action>` /
:ref:`cover.template.publish <cover-template-publish_action>` / :ref:`switch.template.publish <switch-template-publish_action>` /
:ref:`text_sensor.template.publish <text_sensor-template-publish_action>`
- :ref:`stepper.set_target <stepper-set_target_action>` / :ref:`stepper.report_position <stepper-report_position_action>`
- :ref:`servo.write <servo-write_action>`
.. _config-condition:

1
images/camera.svg Normal file
View File

@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24"><path d="M4 4h3l2-2h6l2 2h3a2 2 0 0 1 2 2v12a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2m8 3a5 5 0 0 0-5 5 5 5 0 0 0 5 5 5 5 0 0 0 5-5 5 5 0 0 0-5-5m0 2a3 3 0 0 1 3 3 3 3 0 0 1-3 3 3 3 0 0 1-3-3 3 3 0 0 1 3-3z"/></svg>
Side by Side

After

Width:  |  Height:  |  Size: 283 B

1
images/servo.svg Normal file
View File

@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" height="61.333" width="212"><path d="M20 1.333h172c10.31 0 18.667 8.358 18.667 18.667v21.333C210.667 51.643 202.309 60 192 60H20C9.69 60 1.333 51.643 1.333 41.333V20C1.333 9.69 9.691 1.333 20 1.333z"/><path d="M20 1.333h172c10.31 0 18.667 8.358 18.667 18.667v21.333C210.667 51.643 202.309 60 192 60H20C9.69 60 1.333 51.643 1.333 41.333V20C1.333 9.69 9.691 1.333 20 1.333z" fill="none" stroke="#000" stroke-width="1.3333" stroke-linecap="round" stroke-linejoin="round" stroke-miterlimit="10"/><g aria-label="SERVO" fill="#fff"><path d="M26.92 48.08q-4.06 0-7.933-.887-3.827-.933-6.3-2.473l3.547-8.027q2.333 1.354 5.226 2.194 2.894.793 5.554.793 2.286 0 3.266-.42.98-.467.98-1.353 0-1.027-1.306-1.54-1.26-.514-4.2-1.12-3.78-.794-6.3-1.68-2.52-.934-4.387-2.987-1.867-2.1-1.867-5.647 0-3.08 1.727-5.6 1.727-2.52 5.133-3.966 3.454-1.447 8.354-1.447 3.36 0 6.58.747 3.266.7 5.74 2.1l-3.314 7.98q-4.806-2.427-9.1-2.427-4.246 0-4.246 2.053 0 .98 1.26 1.494 1.26.466 4.153 1.026 3.733.7 6.3 1.634 2.567.886 4.433 2.94 1.914 2.053 1.914 5.6 0 3.08-1.727 5.6-1.727 2.473-5.18 3.966-3.407 1.447-8.307 1.447zM76.56 39.027v8.306H49.4V14.667h26.554v8.306H60.227V26.8H74.04v7.933H60.227v4.294zM98.807 39.12H95.82v8.213H84.807V14.667h15.727q4.526 0 7.886 1.493 3.36 1.493 5.18 4.293 1.82 2.8 1.82 6.534 0 3.5-1.586 6.113-1.587 2.613-4.574 4.153l6.86 10.08h-11.76zm5.507-12.133q0-1.82-1.12-2.8-1.12-1.027-3.36-1.027H95.82v7.653h4.014q2.24 0 3.36-.98 1.12-1.026 1.12-2.846zM158.434 14.667L144.62 47.333h-10.826L119.98 14.667h11.854l7.793 19.086 7.98-19.086zM180.214 48.08q-5.274 0-9.474-2.193-4.2-2.194-6.58-6.067-2.38-3.92-2.38-8.82t2.38-8.773q2.38-3.92 6.58-6.114 4.2-2.193 9.474-2.193 5.273 0 9.473 2.193 4.2 2.194 6.58 6.114 2.38 3.873 2.38 8.773 0 4.9-2.38 8.82-2.38 3.873-6.58 6.067-4.2 2.193-9.473 2.193zm0-8.913q2.053 0 3.686-.98 1.68-1.027 2.66-2.847.98-1.867.98-4.34t-.98-4.293q-.98-1.867-2.66-2.847-1.633-1.027-3.686-1.027-2.054 0-3.734 1.027-1.633.98-2.613 2.847-.98 1.82-.98 4.293t.98 4.34q.98 1.82 2.613 2.847 1.68.98 3.734.98z"/></g></svg>
Side by Side

After

Width:  |  Height:  |  Size: 2.0 KiB

2
index.rst
View File

@ -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
----------------------------