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

Cookbook ape (#334) 

* cookbook-ape

* Optimize SVG

* Update cookbook/arduino_port_extender.rst

Co-Authored-By: Otto Winter <otto@otto-winter.com>

* Update cookbook/arduino_port_extender.rst

Co-Authored-By: Otto Winter <otto@otto-winter.com>

* Update cookbook/arduino_port_extender.rst

Co-Authored-By: Otto Winter <otto@otto-winter.com>

* Update cookbook/arduino_port_extender.rst

Co-Authored-By: Otto Winter <otto@otto-winter.com>

* updates

* fixed indents

* whitespace

* whitespace

* Minor corrections
This commit is contained in:
Guillermo Ruffino 2019-10-19 17:24:47 -03:00 committed by GitHub
parent 52cbfe59cd
commit 9e003f2010
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 328 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

326
cookbook/arduino_port_extender.rst Normal file
View File

@ -0,0 +1,326 @@
Arduino Port Expander
=====================
.. seo::
:description: Instructions on using an Arduino board, like the Pro Mini for expanding ports of a ESPHome node
:image: arduino_pro_mini.jpg
:keywords: Arduino port expander extender ESPHome
With this sketch you can control pins of a remote Arduino board through ESPHome. The Arduino acts as a port
expander, allowing you to use more pins than a standard ESP8266/ESP32 has.
.. figure:: images/arduino_pro_mini.jpg
:align: center
:width: 75.0%
The Arduino is connected to the ESP via I²C. Most Arduinos use the ``A4`` and ``A5`` pins for the I²C bus
so those pins are not available to read from ESPHome.
It is recommended to use a 3.3V I/O level Arduino, however using 5V Arduinos seems to work too. In the latter
case you should power your 5V Arduino with 3.3V otherwise you will need a level converter for the
I²C bus.
Currently it is supported:
- reading digital inputs
- reading analog inputs
- writing digital outputs
The Arduino sketch can be retrieved from `here <https://github.com/glmnet/esphome_devices/tree/master/ArduinoPortExpander/src>`__
you can rename it to ``.ino`` and use the Arduino IDE to program it.
You need to download `arduino_port_expander.h <https://github.com/glmnet/esphome_devices/blob/master/arduino_port_expander.h>`__ and include the ape.h in the ESPHome configuration.
.. code-block:: yaml
esphome:
# ...
includes:
- arduino_port_expander.h
Setup your :ref:`I²C Bus <i2c>` and assign it an ``id``:
.. code-block:: yaml
i2c:
id: i2c_component
By default ESP8266 uses ``SDA`` pin ``GPIO4`` which you need to connect to Arduino's ``A4`` and the ``SCL``
is ``GPIO5`` which goes to Arduino's ``A5``.
Then create a ``custom_component``, this will be the main component we will be referencing later when creating
individual IOs.
.. code-block:: yaml
custom_component:
- id: ape
lambda: |-
auto ape_component = new ArduinoPortExpander(i2c_component, 0x08);
return {ape_component};
By default the I²C address is ``0x08`` but you can change it on the arduino sketch so you can have more slaves
on the same bus.
Now it is time to add the ports.
Binary_Sensor
-------------
When adding binary sensors the pins are configured as INPUT_PULLUP, you can use any PIN from 0 to 13 or
``A0`` to ``A3`` (``A4`` and ``A5`` are used for I²C and ``A6`` and ``A7`` do not support internal pull up)
.. note::
Arduino PIN 13 usually has a LED conected to it and using it as digital input with the built in internal
pull up might be problematic, using it as an output is preferred.
To setup binary sensors, create a custom platform as below, list in braces all the sensors you want,
in the example below two binary sensors are declared on pin 9 and A0 (number 14)
Then declare the ESPHome reference of the binary sensor in the same order as declared in the lambda:
.. code-block:: yaml
binary_sensor:
- platform: custom
lambda: |-
return {ape_binary_sensor(ape, 9),
ape_binary_sensor(ape, 14) // 14 = A0
};
binary_sensors:
- id: binary_sensor_pin2
name: Binary sensor pin 2
- id: binary_sensor_pin3
name: Binary sensor pin 3
on_press:
...
The listed ``binary_sensors`` supports all options from :ref:`Binary Sensor <config-binary_sensor>` like
automations and filters.
Sensor
------
Sensors allows for reading the analog value of an analog pin, those are from ``A0`` to ``A7`` except for
``A4`` and ``A5``. The value returned goes from 0 to 1023 (the value returned by the arduino ``analogRead``
function).
Arduino analog inputs measures voltage. By default the sketch is configured to use the Arduino internal VREF
comparer setup to 1 volt, so voltages bigger are read as 1023. You can configure Arduino to compare the
voltage to VIN voltage, this voltage might be 5 volts or 3.3 volts, depending on how you are powering it. To
do so, pass an additional true value to the hub constructor:
.. code-block:: cpp
auto ape_component = new ArduinoPortExpander(i2c_component, 0x08, true);
To setup sensors, create a custom platform as below, list in braces all the sensors you want,
in the example below two sensors are declared on pin ``A1`` and ``A2``
Then declare the ESPHome reference of the sensor in the same order as declared in the lambda:
.. code-block:: yaml
sensor:
- platform: custom
lambda: |-
return {ape_analog_input(ape, 1), // 1 = A1
ape_analog_input(ape, 2)};
sensors:
- name: Analog A1
id: analog_a1
filters:
- throttle: 1s
- name: Analog A2
id: analog_a2
filters:
- throttle: 2s
The listed ``sensors`` supports all options from :ref:`Sensor <config-sensor>` like
automations and filters.
.. note::
Sensors are polled by default every loop cycle so it is recommended to use the ``throttle`` filter
to not flood the network.
Output
------
Arduinos binary outputs are supported in pins from 0 to 13.
To setup outputs, create a custom platform as below, list in braces all the outputs you want,
in the example below two outputs are declared on pin ``3`` and ``4``
.. code-block:: yaml
output:
- platform: custom
type: binary
lambda: |-
return {ape_binary_output(ape, 3),
ape_binary_output(ape, 4)};
outputs:
- id: output_pin_3
inverted: true
- id: output_pin_4
inverted: true
switch:
- platform: output
name: Switch pin 3
output: output_pin_3
light:
- platform: binary
name: Switch pin 4
output: output_pin_4
Full Example
------------
Let's connect a 4 channel relay board and 2 push buttons to toggle the relays, a PIR sensor, a window and a door
a LM35 temperature sensor and a voltage sensor. Seems a bit too much for an ESP8266? You'll still have some
spares I/Os.
.. code-block:: yaml
esphome:
name: test_arduino
platform: ESP8266
board: nodemcu
includes:
- arduino_port_expander.h
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_pass
api:
ota:
# define i2c device
# for an ESP8266 SDA is D2 and goes to Arduino's A4
# SCL is D1 and goes to Arduino's A5
i2c:
id: i2c_component
logger:
level: DEBUG
# define the port expander hub, here we define one with id 'expander1',
# but you can define many
custom_component:
- id: expander1
lambda: |-
auto expander = new ArduinoPortExpander(i2c_component, 0x08, true);
return {expander};
# define binary outputs, here we have 4, as the relays are inverse logic
# (a path to ground turns the relay ON), we defined the inverted: true
# option of ESPHome outputs.
output:
- platform: custom
type: binary
lambda: |-
return {ape_binary_output(expander1, 2),
ape_binary_output(expander1, 3),
ape_binary_output(expander1, 4),
ape_binary_output(expander1, 5)};
outputs:
- id: relay_1
inverted: true
- id: relay_2
inverted: true
- id: relay_3
inverted: true
- id: relay_4
inverted: true
# connect lights to the first 2 relays
light:
- platform: binary
id: ceiling_light
name: Ceiling light
output: relay_1
- platform: binary
id: room_light
name: Living room light
output: relay_2
# connect a fan to the third relay
fan:
- platform: binary
id: ceiling_fan
output: relay_3
name: Ceiling fan
# connect a pump to the 4th relay
switch:
- platform: output
name: Tank pump
id: tank_pump
output: relay_4
# define binary sensors, use the Arduino PIN number for digital pins and
# for analog use 14 for A0, 15 for A1 and so on...
binary_sensor:
- platform: custom
lambda: |-
return {ape_binary_sensor(expander1, 7),
ape_binary_sensor(expander1, 8),
ape_binary_sensor(expander1, 9),
ape_binary_sensor(expander1, 10),
ape_binary_sensor(expander1, 14) // 14 = A0
};
binary_sensors:
- id: push_button1
internal: true # don't show on HA
on_press:
- light.toggle: ceiling_light
- id: push_button2
internal: true # don't show on HA
on_press:
- light.toggle: room_light
- id: pir_sensor
name: Living PIR
device_class: motion
- id: window_reed_switch
name: Living Window
device_class: window
- id: garage_door
name: Garage garage
device_class: garage_door
# define analog sensors
sensor:
- platform: custom
lambda: |-
return {ape_analog_input(expander1, 1), // 1 = A1
ape_analog_input(expander1, 2)};
sensors:
- name: LM35 Living room temperature
id: lm35_temp
filters:
# update every 60s
- throttle: 60s
# LM35 outputs 0.01v per ºC, and 1023 means 3.3 volts
- lambda: return x * 330.0 / 1023.0;
- name: Analog A2
id: analog_a2
filters:
- throttle: 2s
See Also
--------
- :doc:`/devices/nodemcu_esp8266`
- :ghedit:`Edit`

BIN
cookbook/images/arduino_pro_mini.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 34 KiB

1
images/arduino_logo.svg Normal file
View File

@ -0,0 +1 @@
<svg xmlns="http://www.w3.org/2000/svg" preserveAspectRatio="xMinYMin meet" height="490" width="720"><path d="M174 30a145.545 140 0 0 0 0 280C364 320 344 30 544 30a145.545 140 0 0 1 0 280C354 320 374 30 174 30" fill="none" stroke="#00979c" stroke-width="60"/><g fill="#00979c" stroke="#00979c" stroke-width="20"><path d="M528.069 204.674v-32.78h-32.536v-13.7h32.536V125.66h13.862v32.536h32.536v13.699H541.93v32.78z"/></g><path d="M681.55 29.285V15.73h-5.155v-2.363h13.007v2.363h-5.195v13.555zm9.63 0V13.367h3.906l4.023 12.715 3.887-12.715h3.828v15.918h-2.422v-13.36l-4.101 13.36h-2.403l-4.277-13.555v13.555z" fill="#00979c" stroke="#00979c"/><g stroke-width="2.398" text-anchor="left" letter-spacing=".1em" fill="#00979c" stroke="#00979c"><path d="M83.276 494.845l-6.409-22.963H36.281l-6.586 22.963H7.978l34.444-116.329H73.04l34.445 116.33zM56.84 399.878l-15.309 54.114h30.44zM178.154 494.845l-16.376-37.382c-1.543-3.56-3.694-6.245-6.453-8.054-2.76-1.81-6.008-2.715-9.746-2.715h-4.183v48.151H119.5V378.516h33.911c6.408 0 12.223.55 17.445 1.647 5.222 1.098 9.672 2.922 13.35 5.474 3.68 2.551 6.513 5.874 8.5 9.968 1.988 4.095 2.982 9.109 2.982 15.042 0 4.272-.623 8.07-1.869 11.393-1.246 3.323-2.996 6.186-5.251 8.589-2.255 2.403-4.94 4.346-8.055 5.83-3.115 1.483-6.512 2.521-10.19 3.115 2.847.593 5.458 2.21 7.831 4.85 2.374 2.64 4.747 6.453 7.12 11.437l18.603 38.984zm-5.429-82.062c0-5.696-1.81-9.79-5.43-12.282-3.619-2.492-9.048-3.739-16.287-3.739h-9.612v32.843h8.9c3.382 0 6.453-.356 9.212-1.068 2.76-.712 5.118-1.78 7.076-3.204 1.958-1.424 3.471-3.19 4.54-5.296 1.067-2.106 1.601-4.524 1.601-7.254zM303.918 435.212c0 9.02-1.113 17.208-3.338 24.566-2.225 7.357-5.696 13.632-10.413 18.824-4.718 5.192-10.755 9.197-18.113 12.016-7.357 2.818-16.169 4.227-26.434 4.227h-29.55V378.516h34.445c8.9 0 16.689 1.113 23.364 3.338 6.675 2.225 12.238 5.652 16.688 10.28 4.45 4.628 7.788 10.503 10.013 17.623 2.225 7.12 3.338 15.606 3.338 25.455zm-23.497 1.424c0-6.29-.505-11.896-1.513-16.821-1.01-4.925-2.715-9.094-5.118-12.506-2.403-3.411-5.622-6.007-9.657-7.788-4.035-1.78-9.049-2.67-15.042-2.67h-11.125v79.66h9.612c10.74 0 18.899-3.205 24.476-9.613 5.578-6.408 8.367-16.496 8.367-30.262zM401.289 452.034c0 7.417-.994 13.93-2.982 19.537-1.987 5.607-4.836 10.28-8.544 14.018-3.709 3.738-8.233 6.557-13.573 8.455-5.34 1.9-11.334 2.849-17.98 2.849-7.476 0-13.884-.95-19.224-2.849-5.34-1.898-9.672-4.628-12.995-8.188-3.323-3.56-5.726-7.892-7.21-12.995-1.483-5.103-2.224-10.829-2.224-17.178v-77.167h21.895v75.832c0 3.917.34 7.388 1.023 10.414.683 3.026 1.87 5.592 3.56 7.699 1.692 2.106 3.813 3.693 6.364 4.762 2.552 1.068 5.756 1.602 9.613 1.602 3.62 0 6.675-.46 9.167-1.38 2.492-.92 4.57-2.403 6.23-4.45 1.662-2.047 2.908-4.673 3.739-7.877.83-3.204 1.246-7.09 1.246-11.66v-74.942h21.895zM422.561 396.406v-17.89h73.518v17.89h-25.633v80.371h25.633v18.068h-73.518v-18.068h25.633v-80.37zM575.471 494.845l-31.152-69.423-6.408-14.953v84.376h-19.937V378.516h26.88l31.774 69.869 5.607 13.618v-83.486h19.937v116.328zM706.93 436.191c0 10.562-1.23 19.67-3.693 27.325-2.462 7.654-5.845 13.944-10.146 18.869-4.302 4.925-9.346 8.574-15.131 10.947-5.786 2.374-11.971 3.56-18.558 3.56-15.308 0-26.82-5.088-34.533-15.264-7.714-10.176-11.571-24.966-11.571-44.369 0-10.561 1.231-19.67 3.694-27.324 2.462-7.654 5.844-13.944 10.146-18.869 4.302-4.925 9.346-8.574 15.131-10.948 5.785-2.373 11.971-3.56 18.557-3.56 15.31 0 26.82 5.074 34.534 15.22 7.714 10.147 11.57 24.951 11.57 44.413zm-23.14 1.068c0-13.766-1.84-24.03-5.519-30.795-3.679-6.764-9.73-10.147-18.157-10.147-4.213 0-7.802.876-10.77 2.626-2.966 1.75-5.414 4.317-7.342 7.699-1.928 3.382-3.338 7.55-4.228 12.505-.89 4.955-1.335 10.636-1.335 17.044 0 13.766 1.854 24.032 5.563 30.796 3.708 6.764 9.746 10.147 18.112 10.147 4.213 0 7.818-.876 10.814-2.626 2.997-1.75 5.445-4.317 7.343-7.699 1.9-3.382 3.293-7.55 4.184-12.505.89-4.955 1.335-10.636 1.335-17.045z" transform="scale(1.01716 .98313)"/></g><g fill="#00979c" stroke="#00979c" stroke-width="20"><path d="M321.418 266.309v-17.43h53.253v17.43z" transform="matrix(1.5646 0 0 .63914 -365.795 .528)" stroke-width="23.619"/></g></svg>
Side by Side

After

Width:  |  Height:  |  Size: 4.0 KiB

1
index.rst
View File

@ -313,6 +313,7 @@ Cookbook
.. imgtable::
Arduino Port Extender, cookbook/arduino_port_extender, arduino_logo.svg
Endstop Cover, cookbook/endstop-cover, window-open.svg
PIR Sensor, cookbook/pir, pir.jpg
Relay, cookbook/relay, relay.jpg