mirror of
https://github.com/esphome/esphome-docs.git
synced 2024-08-31 00:19:54 +02:00
328 lines
9.7 KiB
ReStructuredText
328 lines
9.7 KiB
ReStructuredText
Arduino Port Expander
|
|
=====================
|
|
|
|
.. seo::
|
|
:description: Instructions on using an Arduino board, like the Pro Mini for expanding ports of an 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://gist.github.com/glmnet/49ca3d6a9742fc3649f4fbdeaa4cdf5d#file-arduino_port_expander_sketch-ino>`__
|
|
you can rename it to ``.ino`` and use the Arduino IDE to program it.
|
|
|
|
You need to download `arduino_port_expander.h <https://gist.github.com/glmnet/49ca3d6a9742fc3649f4fbdeaa4cdf5d#file-arduino_port_expander-h>`__
|
|
and include the arduino_port_expander.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 devices
|
|
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 connected 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`
|