Upstream/esphome-docs
1
0
Fork 0
mirror of https://github.com/esphome/esphome-docs.git synced 2025-01-13 20:11:53 +01:00
Code Issues Projects Releases Wiki Activity

Merge branch 'next' into rc

Browse Source
This commit is contained in:
Otto Winter 2018-10-31 16:40:25 +01:00
commit 9e5cc9cfc3
No known key found for this signature in database
GPG Key ID: DB66C0BE6013F97E
17 changed files with 329 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
api/misc/stepper.rst Normal file
View File

@ -0,0 +1,35 @@
Stepper Component
=================
.. cpp:namespace:: nullptr
API Reference
-------------
.. cpp:namespace:: nullptr
Stepper
*******
.. doxygenclass:: stepper::Stepper
:members:
:protected-members:
:undoc-members:
.. doxygenclass:: stepper::SetTargetAction
:members:
:protected-members:
:undoc-members:
.. doxygenclass:: stepper::ReportPositionAction
:members:
:protected-members:
:undoc-members:
A4988
*****
.. doxygenclass:: stepper::A4988
:members:
:protected-members:
:undoc-members:

5
esphomeyaml/components/display/index.rst
View File

@ -297,6 +297,11 @@ use any string you pass it, like ``"ON"`` or ``"OFF"``.
// Shorthand:
it.printf(0, 0, id(my_font), "State: %s", id(my_binary_sensor).state ? "ON" : "OFF");
.. note::
For displaying external data on the display, for example data from your Home Assistant instance,
you can use the :doc:`/esphomeyaml/components/text_sensor/mqtt` (see the example there for more information).
.. _display-strftime:
Displaying Time

13
esphomeyaml/components/esp32_ble_beacon.rst
View File

@ -67,19 +67,6 @@ know when I'm home or away.
:align: center
:width: 75.0%
.. note::
The latest arduino ESP32 framework has a bug with the bluetooth module. Please set
:ref:`esphomeyaml-arduino_version` to ``espressif32@1.0.2`` like so:
.. code:: yaml
esphomeyaml:
# ...
arduino_version: espressif32@1.0.2
See https://github.com/OttoWinter/esphomeyaml/issues/78#issuecomment-425746566
See Also
--------

14
esphomeyaml/components/esp32_ble_tracker.rst
View File

@ -43,20 +43,6 @@ for information on how you can find out the MAC address of a device and track it
battery_level:
name: "Xiaomi MiJia Battery Level"
.. note::
The latest arduino ESP32 framework has a bug with the bluetooth module. Please set
:ref:`esphomeyaml-arduino_version` to ``espressif32@1.0.2`` like so:
.. code:: yaml
esphomeyaml:
# ...
arduino_version: espressif32@1.0.2
See https://github.com/OttoWinter/esphomeyaml/issues/78#issuecomment-425746566
.. note::
The first time this component is enabled for an ESP32, the code partition needs to be

41
esphomeyaml/components/mqtt.rst
View File

@ -313,6 +313,16 @@ Configuration variables:
then:
- # ...
.. note::
This action can also be used in :ref:`lambdas <config-lambda>`:
.. code:: cpp
App.get_mqtt_client()->subscribe("the/topic", [=](const std::string &payload) {
// do something with payload
});
.. _mqtt-on_json_message:
``on_json_message`` Trigger
@ -366,6 +376,16 @@ Configuration variables:
Due to the way this trigger works internally it is incompatible with certain actions and will
trigger a compile failure. For example with the ``delay`` action.
.. note::
This action can also be used in :ref:`lambdas <config-lambda>`:
.. code:: cpp
App.get_mqtt_client()->subscribe_json("the/topic", [=](JsonObject &root) {
// do something with JSON-decoded value root
});
.. _mqtt-publish_action:
``mqtt.publish`` Action
@ -413,8 +433,7 @@ Configuration options:
.. code:: cpp
// in lambda, parameters: <TOPIC>, <PAYLOAD>, <QoS>, <retain>
id(mqtt_client).publish("the/topic", "The Payload", 0, false);
id(mqtt_client).publish("the/topic", "The Payload");
.. _mqtt-publish_json_action:
@ -452,6 +471,24 @@ Configuration options:
- **retain** (*Optional*, boolean): If the published message should
have a retain flag on or not. Defaults to ``False``.
.. note::
This action can also be written in :ref:`lambdas <config-lambda>`:
.. code:: yaml
mqtt:
# Give the mqtt component an ID
id: mqtt_client
.. code:: cpp
id(mqtt_client).publish_json("the/topic", [=](JsonObject &root) {
root["something"] = id(my_sensor).value;
});
See Also
--------

4
esphomeyaml/components/sensor/cse7766.rst
View File

@ -12,7 +12,7 @@ esphomelib. This sensor is commonly found in Sonoff POW R2.
As the communication with the CSE7766 done using UART, you need
to have an :ref:`UART bus <uart>` in your configuration with the ``rx_pin`` connected to the CSE7766.
Additionally, you need to set the baud rate to 9600.
Additionally, you need to set the baud rate to 4800.
.. code:: yaml
@ -23,7 +23,7 @@ Additionally, you need to set the baud rate to 9600.
uart:
rx_pin: RX
baud_rate: 9600
baud_rate: 4800
sensor:
- platform: cse7766

3
esphomeyaml/components/sensor/index.rst
View File

@ -126,6 +126,9 @@ every filter there is currently:
- **send_every**: How often a sensor value should be pushed out. For
example, in above configuration the weighted average is only
pushed out on every 15th received sensor value.
- **send_first_at**: By default, the very first raw value on boot is immediately
published. With this parameter you can specify when the very first value is to be sent.
Defaults to ``1``.
- **exponential_moving_average**: A simple `exponential moving
average <https://en.wikipedia.org/wiki/Moving_average#Exponential_moving_average>`__

164
esphomeyaml/components/stepper/index.rst Normal file
View File

@ -0,0 +1,164 @@
Stepper Component
=================
The ``stepper`` component allows you to use stepper motors with esphomelib.
Currently only the A4988 stepper driver
(`datasheet <https://www.pololu.com/file/0J450/a4988_DMOS_microstepping_driver_with_translator.pdf>`__)
is supported.
.. code:: yaml
# Example configuration entry
stepper:
- platform: a4988
id: my_stepper
step_pin: D0
dir_pin: D1
max_speed: 250 steps/s
# Optional:
sleep_pin: D2
acceleration: inf
deceleration: inf
Configuration variables:
------------------------
- **id** (**Required**, :ref:`config-id`): Specify the ID of the stepper so that you can control it.
- **step_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The ``STEP`` pin of the A4988
stepper driver.
- **dir_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The ``DIRECTION`` pin of the A4988
stepper driver.
- **max_speed** (**Required**, float): The maximum speed in ``steps/s`` (steps per seconds) to drive the
stepper at. Note most steppers can't step properly with speeds higher than 250 steps/s.
- **sleep_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): Optionally also use the ``SLEEP`` pin
of the A4988 stepper driver. If specified, the driver will be put into sleep mode as soon as the stepper
reaches the target steps.
- **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.
- **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).
.. note::
Esphomelib's core loop only runs 60 times per second by default to conserve power. But this also means it's limited
to 60 steps per second. To have higher step rater, you have to open up the ``<NODE_NAME>/src/main.cpp`` file,
scroll down to the ``void loop()`` section and remove the ``delay(16);`` line.
.. note::
If the stepper is driving in the wrong direction, you can invert the ``dir_pin``:
.. code:: yaml
stepper:
- platform: a4988
# ...
dir_pin:
number: D1
inverted: True
.. _stepper-set_target_action:
``stepper.set_target`` Action
-----------------------------
To use your stepper motor in :ref:`automations <automation>` or templates, you can use this action to set the target
position (in steps). The stepper will always run towards the target position and stop once it has reached the target.
.. code:: yaml
on_...:
then:
- stepper.set_target:
id: my_stepper
target: 250
# Templated
- stepper.set_target:
id: my_stepper
target: !lambda |-
if (id(my_binary_sensor).value) {
return 1000;
} else {
return -1000;
}
Configuration options:
- **id** (**Required**, :ref:`config-id`): The ID of the stepper.
- **target** (*Optional*, int, :ref:`templatable <config-templatable>`): The target position in steps.
.. note::
This action can also be expressed as a :ref:`lambda <config-lambda>`:
.. code:: cpp
id(my_stepper).set_target(250);
// Get the currently set target position:
int target = id(my_stepper).target_position;
.. _stepper-report_position_action:
``stepper.report_position`` Action
----------------------------------
All steppers start out with a target and current position of ``0`` on boot. However, if you for example want to home
a stepper motor, it can be useful to **report** the stepper where it is currently at.
With this action, you can set the stepper's internal position counter to a specific value (in steps). Please note
that reporting the position can create unexpected moves of the stepper. For example, if the stepper's target and
current position is at 1000 steps and you "report" a position of 0, the stepper will move 1000 steps forward to match
the target again.
.. code:: yaml
on_...:
then:
- stepper.report_position:
id: my_stepper
position: 250
# It's best to call set_target directly after report_position, so that the stepper doesn't move
- stepper.set_target:
id: my_stepper
target: 250
# Templated
- stepper.report_position:
id: my_stepper
position: !lambda |-
if (id(my_binary_sensor).value) {
return 0;
} else {
return -1000;
}
Configuration options:
- **id** (**Required**, :ref:`config-id`): The ID of the stepper.
- **target** (*Optional*, int, :ref:`templatable <config-templatable>`): The target position in steps.
.. note::
This action can also be expressed as a :ref:`lambda <config-lambda>`:
.. code:: cpp
id(my_stepper).report_position(250);
// Get the current position:
int pos = id(my_stepper).current_position;
See Also
--------
- :doc:`API Reference </api/misc/stepper>`
- `Edit this page on GitHub <https://github.com/OttoWinter/esphomedocs/blob/current/esphomeyaml/components/stepper.rst>`__
.. disqus::

9
esphomeyaml/components/switch/index.rst
View File

@ -37,8 +37,7 @@ This action toggles a switch with the given ID when executed.
on_...:
then:
- switch.toggle:
id: relay_1
- switch.toggle: id: relay_1
.. _switch-turn_on_action:
@ -51,8 +50,7 @@ This action turns a switch with the given ID on when executed.
on_...:
then:
- switch.turn_on:
id: relay_1
- switch.turn_on: relay_1
.. _switch-turn_off_action:
@ -65,8 +63,7 @@ This action turns a switch with the given ID off when executed.
on_...:
then:
- switch.turn_off:
id: relay_1
- switch.turn_off: relay_1
lambda calls
************

8
esphomeyaml/components/text_sensor/index.rst
View File

@ -60,19 +60,19 @@ lambda calls
From :ref:`lambdas <config-lambda>`, you can call several methods on all text sensors to do some
advanced stuff (see the full :doc:`API Reference </api/sensor/index>` for more info).
- ``push_new_value()``: Manually cause the sensor to push out a value.
- ``publish_state()``: Manually cause the sensor to push out a value.
.. code:: yaml
// Within lambda, push a value of "Hello World"
id(my_sensor).push_new_value("Hello World");
id(my_sensor).publish_state("Hello World");
- ``value``: Retrieve the current value of the sensor as an ``std::string`` object.
- ``.state``: Retrieve the current value of the sensor as an ``std::string`` object.
.. code:: yaml
// For example, create a custom log message when a value is received:
std::string val = id(my_sensor).value;
std::string val = id(my_sensor).state;
ESP_LOGI("main", "Value of my sensor: %s", val.c_str());
See Also

4
esphomeyaml/components/text_sensor/mqtt_subscribe.rst
View File

@ -27,7 +27,7 @@ Example Usage for Displays
--------------------------
This integration is especially useful for displays, to show external data on the display.
Please note you have to use the ``.c_str()`` method on the value object together with the ``%s`` format
Please note you have to use the ``.c_str()`` method on the ``.state`` object together with the ``%s`` format
to use it in ``printf`` expressions.
.. code:: yaml
@ -43,7 +43,7 @@ to use it in ``printf`` expressions.
- platform: ...
# ...
lambda: |-
it.printf("The data is: %s", id(font), id(mysensor).value.c_str());
it.printf(0, 0, id(font), "The data is: %s", id(mysensor).state.c_str());
See Also
--------

13
esphomeyaml/cookbook/power_meter.rst
View File

@ -41,6 +41,19 @@ Thus, rearranging the expression yields a proportional factor of ``0.06`` from `
And if a technician shows up and he looks confused about what the heck you have done to your
power meter, tell them about esphomelib 😉
.. note::
Photoresistors often have a bit of noise during their switching phases. So in certain situations,
a single power meter tick can result in many pulses being counted. This effect is especially big on
ESP8266s. If you're experiencing this, try enabling the ``internal_filter:`` filter option:
.. code:: yaml
sensor:
- platform: pulse_counter
# ...
internal_filter: 10us
See Also
--------

15
esphomeyaml/guides/automations.rst
View File

@ -362,13 +362,14 @@ turns on a light for 5 seconds. Otherwise, the light is turned off immediately.
on_...:
then:
- if:
lambda: 'return id(some_sensor).state < 30;'
then:
- lambda: 'ESP_LOGD("main", "The sensor value is below 30!");
- light.turn_on: my_light
- delay: 5s
else:
- lambda: 'ESP_LOGD("main", "The sensor value is above 30!");
condition:
lambda: 'return id(some_sensor).state < 30;'
then:
- lambda: 'ESP_LOGD("main", "The sensor value is below 30!");
- light.turn_on: my_light
- delay: 5s
else:
- lambda: 'ESP_LOGD("main", "The sensor value is above 30!");
- light.turn_off: my_light

16
esphomeyaml/guides/getting_started_command_line.rst
View File

@ -18,7 +18,7 @@ Installing esphomeyaml is very easy. All you need to do is have `Python
pip install esphomeyaml
Alternatively, there’s also a docker image available for easy
installation (the docker hub image is only available for amd64 right now, if you have
installation (the docker hub image is only available for amd64 right now; if you have
an RPi, please install esphomelib through ``pip`` or use :doc:`the HassIO add-on <getting_started_hassio>`:
.. code:: bash
@ -64,11 +64,11 @@ GPIO switch </esphomeyaml/components/switch/gpio>` to our app.
The configuration format should hopefully immediately seem similar to
you. esphomeyaml has tried to keep it as close to Home Assistant’s
``configuration.yaml`` schema as possible. In above example, we’re
simply adding a switch that’s called “Living Room Relay” (could control
``configuration.yaml`` schema as possible. In the above example, we’re
simply adding a switch that’s called “Living Room Dehumidifier” (could control
anything really, for example lights) and is connected to pin ``GPIO5``.
The nice thing about esphomeyaml is that it will automatically also try
to translate pin numbers for you based on the board. For example in
to translate pin numbers for you based on the board. For example in the
above configuration, if using a NodeMCU board, you could have just as
well set ``D1`` as the ``pin:`` option.
@ -132,7 +132,7 @@ Sensor </esphomeyaml/components/binary_sensor/gpio>`.
inverted: True
mode: INPUT_PULLUP
This is an advanced feature of esphomeyaml, almost all pins can
This is an advanced feature of esphomeyaml. Almost all pins can
optionally have a more complicated configuration schema with options for
inversion and pinMode - the :ref:`Pin Schema <config-pin_schema>`.
@ -157,8 +157,8 @@ and uploaded your first esphomelib custom firmware to your node. You’ve
also learned how to enable some basic components via the configuration
file.
So now is a great time to go take a look at the :doc:`Components Index </esphomeyaml/index>`,
hopefully you’ll find all sensors/outputs/… you’ll need in there. If you’re having any problems or
So now is a great time to go take a look at the :doc:`Components Index </esphomeyaml/index>`.
Hopefully you’ll find all sensors/outputs/… you’ll need in there. If you’re having any problems or
want new features, please either create a new issue on the `GitHub issue
tracker <https://github.com/OttoWinter/esphomeyaml/issues>`__ or contact
me via the `Discord chat <https://discord.gg/KhAMKrd>`__.
@ -166,7 +166,7 @@ me via the `Discord chat <https://discord.gg/KhAMKrd>`__.
Bonus: esphomeyaml dashboard
----------------------------
Starting with version 1.6.0 esphomeyaml features a dashboard that you can use to
Starting with version 1.6.0, esphomeyaml features a dashboard that you can use to
easily manage your nodes from a nice web interface. It was primarily designed for
:doc:`the HassIO add-on <getting_started_hassio>`, but also works with a simple command.

36
esphomeyaml/images/stepper.svg Normal file
View File

@ -0,0 +1,36 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<svg
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:cc="http://creativecommons.org/ns#"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns="http://www.w3.org/2000/svg"
viewBox="0 0 280 60"
height="60"
width="280"
xml:space="preserve"
id="svg2"
version="1.1"><metadata
id="metadata8"><rdf:RDF><cc:Work
rdf:about=""><dc:format>image/svg+xml</dc:format><dc:type
rdf:resource="http://purl.org/dc/dcmitype/StillImage" /></cc:Work></rdf:RDF></metadata><defs
id="defs6" /><g
transform="matrix(1.3333333,0,0,-1.3333333,0,60)"
id="g10"><g
transform="scale(0.1)"
id="g12"><path
id="path14"
style="fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none"
d="M 151.832,440 H 1948.17 c 77.32,0 140,-62.68 140,-140 V 145 c 0,-77.3203 -62.68,-140 -140,-140 H 151.832 c -77.3203,0 -140,62.6797 -140,140 v 155 c 0,77.32 62.6797,140 140,140 z" /><path
id="path16"
style="fill:none;stroke:#000000;stroke-width:10;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:10;stroke-dasharray:none;stroke-opacity:1"
d="M 151.832,440 H 1948.17 c 77.32,0 140,-62.68 140,-140 V 145 c 0,-77.3203 -62.68,-140 -140,-140 H 151.832 c -77.3164,0 -140,62.6797 -140,140 v 155 c 0,77.32 62.6836,140 140,140 z" /><g
transform="scale(10)"
id="g18"><text
id="text22"
style="font-variant:normal;font-weight:900;font-size:35px;font-family:Montserrat;-inkscape-font-specification:Montserrat-Black;writing-mode:lr-tb;fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:none"
transform="matrix(1,0,0,-1,9.48516,9.75)"><tspan
id="tspan20"
y="0"
x="0 25.645 51.535 78.090004 106.74499 135.39999 161.95499">STEPPER</tspan></text>
</g></g></g></svg>
Side by Side

After

Width:  |  Height:  |  Size: 1.9 KiB

8
esphomeyaml/index.rst
View File

@ -681,9 +681,9 @@ Misc Components
-------------------------------------------------- -------------------------------------------------- --------------------------------------------------
`ESP32 Touch Hub`_ `Status LED`_ `PN532`_
-------------------------------------------------- -------------------------------------------------- --------------------------------------------------
|RDM6300|_ |Time|_
|RDM6300|_ |Time|_ |Stepper|_
-------------------------------------------------- -------------------------------------------------- --------------------------------------------------
`RDM6300`_ `Time`_
`RDM6300`_ `Time`_ `Stepper`_
================================================== ================================================== ==================================================
.. |Dallas Hub| image:: /esphomeyaml/images/dallas.jpg
@ -728,6 +728,10 @@ Misc Components
.. |Time| image:: /esphomeyaml/images/clock-outline.svg
:class: component-image
.. _Time: /esphomeyaml/components/time.html
.. |Stepper| image:: /esphomeyaml/images/stepper.svg
:class: component-image
.. _Stepper: /esphomeyaml/components/stepper.html
.. _cookbook:

1
esphomeyaml/misc.csv
View File

@ -12,3 +12,4 @@ Status LED, components/status_led, led-on.svg
PN532, components/pn532, pn532.jpg
RDM6300, components/rdm6300, rdm6300.jpg
Time, components/time, clock-outline.svg
Stepper, components/stepper/index, stepper.svg

1 Dallas Hub components/dallas dallas.jpg
12 PN532 components/pn532 pn532.jpg
13 RDM6300 components/rdm6300 rdm6300.jpg
14 Time components/time clock-outline.svg
15 Stepper components/stepper/index stepper.svg