Upstream/esphome-docs
1
0
Fork 0
mirror of https://github.com/esphome/esphome-docs.git synced 2024-12-28 17:48:35 +01:00
Code Issues Projects Releases Wiki Activity
025987cb26
esphome-docs/components/display/pvvx_mithermometer.rst

235 lines
8.9 KiB
ReStructuredText
Raw Blame History

PVVX MiThermometer Display
==========================
.. seo::
:description: Instructions for setting up BLE devices with PVVX MiThermometer custom firmware as displays.
:image: /components/sensor/images/xiaomi_lywsd03mmc.jpg
The ``pvvx_mithermometer`` display platform allows you to use devices running the `ATC_MiThermometer firmware <https://github.com/pvvx/ATC_MiThermometer>`__ by pvvx as display drivers with ESPHome.
.. figure:: /components/sensor/images/xiaomi_lywsd03mmc.jpg
:align: center
:width: 75.0%
Xiaomi LYWSD03MMC.
The data to be displayed is transmitted as external data via BLE.
To do this, a ``ble_client`` component must be set up.
This component can also synchronize the time of the pvvx device by transmitting a timestamp on each connection.
After the data has been transmitted, the BLE connection is terminated in order to be able to receive the advertising data required for the ``pvvx_mithermometer`` sensor platform.
The pvvx firmware refreshes the screen periodically (can be set as minimum LCD refresh rate in the firmware configuration).
By default, the internal sensor data and, if available and valid (``validity_period``), the external data are switched every 2.5 s.
Further firmware configuration makes it possible to activate other display modes such as time and battery status.
The firmware configuration can be changed via browser using `TelinkMiFlasher.html <https://pvvx.github.io/ATC_MiThermometer/TelinkMiFlasher.html>`__.
.. code-block:: yaml
# Example configuration entry
esp32_ble_tracker:
ble_client:
- mac_address: XX:XX:XX:XX:XX:XX
id: pvvx_ble_display
display:
- platform: pvvx_mithermometer
ble_client_id: pvvx_ble_display
lambda: |-
it.print_bignum(23.1);
it.print_unit(pvvx_mithermometer::UNIT_DEG_C);
it.print_smallnum(33);
it.print_percent(true);
it.print_happy(true);
it.print_bracket(true);
Configuration variables:
------------------------
- **ble_client_id** (**Required**, :ref:`config-id`): ID of the associated BLE client.
- **time_id** (*Optional*, :ref:`config-id`): ID of a :doc:`/components/time/index`. If set, the time will be synchronized with every connection.
- **disconnect_delay** (*Optional*, :ref:`config-time`): The amount of time the BLE connection is maintained before being disconnected again. Defaults to ``5s``.
- **update_interval** (*Optional*, :ref:`config-time`): The interval to transmit the display data. Defaults to ``60s``.
- **validity_period** (*Optional*, :ref:`config-time`): The time periode for which the pvvx device should display the information. Defaults to ``5min``.
- **lambda** (*Optional*, :ref:`lambda <config-lambda>`): The lambda to use to define the information to be displayed.
See :ref:`display-pvvx_mithermometer_lambda` for more information.
- **auto_clear_enabled** (*Optional*, boolean): Whether to automatically clear the display data before each lambda call,
or to keep the existing display content (must overwrite explicitly, e.g., only on data change). Defaults to ``true``.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
.. _display-pvvx_mithermometer_lambda:
Rendering Lambda
----------------
The ``pvvx_mithermometer`` displays can only show two numbers with optional units and a smiley face. Therefore, the API is tailord to these limitations.
In the lambda you're passed a variable called ``it`` as with all other displays. In this case however, ``it`` is a ``PVVXDisplay`` instance (see API Reference).
.. code-block:: yaml
display:
- platform: pvvx_mithermometer
# ...
lambda: |-
// Print -2.1 as big number (first row)
it.print_bignum(-2.1);
// Print °C next to the big number
it.print_unit(pvvx_mithermometer::UNIT_DEG_C);
// Print 88 as small number (second row)
it.print_smallnum(88);
// Print % next to the small number
it.print_percent(true);
// Print the low battery symbol
it.print_battery(true);
// Print a happy smiley. Results in " ^_^ "
it.print_happy(true);
// Print a sad smiley. Results in " -∧- "
it.print_sad(true);
// The comination of happy and sad simley results in " Δ△Δ "
// Print round brackets around the simley
it.print_bracket(true);
// The final result is "(Δ△Δ)"
Valid values for the big number (``it.print_bignum()``) are from -99.5 to 1999.5. Smaller values are displayed as ``Lo``, larger ones as ``Hi``. It will be printed to the screen. If not defined, a 0 will be displayed.
Valid values for the small number (``it.print_smallnum()``) are from -9 to 99. Smaller values are displayed as ``Lo``, larger ones as ``Hi``. If not defined, a 0 will be displayed.
Possible values for the unit of the big number (``it.print_unit()``) are:
- ``pvvx_mithermometer::UNIT_NONE``: do not show a unit
- ``pvvx_mithermometer::UNIT_DEG_GHE``: show ``°Г``
- ``pvvx_mithermometer::UNIT_MINUS``: show ``-``
- ``pvvx_mithermometer::UNIT_DEG_F``: show ``°F``
- ``pvvx_mithermometer::UNIT_LOWDASH``: show ``_``
- ``pvvx_mithermometer::UNIT_DEG_C``: show ``°C``
- ``pvvx_mithermometer::UNIT_LINES``: show ``=``
- ``pvvx_mithermometer::UNIT_DEG_E``: show ``°E``
The appearance of the smiley can be defined by combining the functions ``it.print_happy()``, ``it.print_sad()`` and ``it.print_bracket(true)``:
=================== =============== ================= ==========
``print_bracket()`` ``print_sad()`` ``print_happy()`` result
=================== =============== ================= ==========
false false false
false false true ``^_^``
false true false ``-∧-``
false true true ``Δ△Δ``
true false false ``( )``
true false true ``(^_^)``
true true false ``(-∧-)``
true true true ``(Δ△Δ)``
=================== =============== ================= ==========
Display states of other sensors
*******************************
The following example display the sensor states of a MiFlora sensor on a pvvx display. The time is also synchronized.
.. code-block:: yaml
time:
- platform: homeassistant
id: homeassistant_time
esp32_ble_tracker:
ble_client:
- mac_address: XX:XX:XX:XX:XX:XX
id: pvvx_ble_display
sensor:
- platform: pvvx_mithermometer
mac_address: XX:XX:XX:XX:XX:XX
temperature:
name: "PVVX Temperature"
humidity:
name: "PVVX Humidity"
battery_level:
name: "PVVX Battery-Level"
battery_voltage:
name: "PVVX Battery-Voltage"
- platform: xiaomi_hhccjcy01
mac_address: XX:XX:XX:XX:XX:XX
temperature:
name: "Xiaomi HHCCJCY01 Temperature"
id: miflora_temperature
moisture:
name: "Xiaomi HHCCJCY01 Moisture"
id: miflora_moisture
illuminance:
name: "Xiaomi HHCCJCY01 Illuminance"
conductivity:
name: "Xiaomi HHCCJCY01 Soil Conductivity"
display:
- platform: pvvx_mithermometer
ble_client_id: pvvx_ble_display
update_interval: 10min
validity_period: 15min
time_id: homeassistant_time
lambda: |-
double temp = id(miflora_temperature).state;
double moisture = id(miflora_moisture).state;
it.print_bignum(temp);
it.print_unit(pvvx_mithermometer::UNIT_DEG_C);
it.print_smallnum(moisture);
it.print_percent();
if (temp < 5 || temp > 30 || moisture < 10 || moisture > 50) {
it.print_sad();
} else {
it.print_happy();
}
Only synchronize the time once a day
************************************
The following example will synchronized the time of the pvvx device once a day.
.. code-block:: yaml
time:
- platform: homeassistant
id: homeassistant_time
esp32_ble_tracker:
ble_client:
- mac_address: XX:XX:XX:XX:XX:XX
id: pvvx_ble_display
sensor:
- platform: pvvx_mithermometer
mac_address: XX:XX:XX:XX:XX:XX
temperature:
name: "PVVX Temperature"
humidity:
name: "PVVX Humidity"
battery_level:
name: "PVVX Battery-Level"
battery_voltage:
name: "PVVX Battery-Voltage"
display:
- platform: pvvx_mithermometer
ble_client_id: pvvx_ble_display
update_interval: 24h
validity_period: 0s
time_id: homeassistant_time
See Also
--------
- :doc:`index`
- :doc:`/components/ble_client`
- :doc:`/components/sensor/xiaomi_ble`
- :apiref:`pvvx_mithermometer/display/pvvx_display.h`
- `ATC_MiThermometer firmware <https://github.com/pvvx/ATC_MiThermometer>`__ by `pvvx <https://github.com/pvvx>`__
- :ghedit:`Edit`
Reference in New Issue View Git Blame Copy Permalink