MicroNova component documentation (#2890)

Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>

components/micronova.rst

@@ -0,0 +1,227 @@
+MicroNova based pellet stove
+============================
+
+.. seo::
+    :description: Instructions for setting up a MicroNova board based pellet stove in ESPHome.
+
+The MicroNova component allows you to integrate a pellet stove with a MicroNova board in ESPHome.
+It uses :ref:`UART <uart>` for communication.
+
+The :ref:`UART <uart>` must be configured with a baud rate 1200, 8 data bits, 2 stop bits, no parity, no flow control.
+
+.. warning::
+
+    MicroNova bords come in various flavours. This code is only tested on an ExtraFlame Ketty Evo 2.0 stove. The protocol is not
+    documented but has been reverse engineerd by others. See the links below for all the info that helped me.
+    The different sensors, buttons and stove switch may require specific **memory_location** and **memory_address** parameters that
+    match your MicroNova specific board.
+
+    Also, switching your stove on or off can behave different on the various MicroNova flavours.
+
+    Use this integration at your own risk.
+
+Connecting your stove
+---------------------
+
+Most MicroNova based pellet stoves have a serial output. In most cases this output has 4 pins: GND, 5v, 20V and DATA.
+
+.. figure:: images/micronova_serial.png
+    :align: center
+    :width: 50.0%
+
+.. figure:: images/micronova_serial_layout.png
+    :align: center
+    :width: 50.0%
+
+You will have to build a simple circuit to interface with your stove. It is based on optocouplers for galvanic separation and logic
+level shifting between 5v and 3V3.
+
+.. figure:: images/micronova_optocouplers.png
+    :align: center
+    :width: 100.0%
+
+    Optocoupler interface circuit (credit: philibertc)
+
+
+
+See the references below for all the details about te circuit.
+
+You can use the 5V output from the stove to power the ESP module, but you will have to put a voltage regulator in between to
+get 3v3.
+
+Component/Hub
+-------------
+
+.. code-block:: yaml
+
+    micronova:
+      enable_rx_pin: REPLACEME
+
+Configuration variables:
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+- **enable_rx_pin** (**Required**, :ref:`config-pin`): Output pin to be used to switch the line between RX and TX.
+- **update_interval** (*Optional*, :ref:`config-time`): The interval that the sensors should be checked.
+  Defaults to 60 seconds.
+
+.. note::
+
+    For all text sensors, sensors, numbers, buttons and switches hereafter most of the the default **memory_location** and **memory_address** parameters will work so you should
+    not specify them. However your Micronova boad may require you to specify alternate values. So every text sensor, button,
+    switch or number accepts these parameters:
+
+    - **memory_location** (*Optional*): The memory location where the parameter must be read. For most stoves this is 0x00 for RAM
+      or 0x20 for EPROM.
+    - **memory_address** (*Optional*): The address where the parameter is stored.
+
+
+Text Sensors
+------------
+
+.. code-block:: yaml
+
+    text_sensor:
+      - platform: micronova
+        stove_state:
+          name: Stove status
+
+Configuration variables:
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+- **stove_state** (*Optional*): The current stove state.
+  All options from :ref:`Text Sensor <config-text_sensor>`.
+
+Sensors
+-------
+
+.. code-block:: yaml
+
+    sensor:
+      - platform: micronova
+        room_temperature:
+          name: Room temperature
+        fumes_temperature:
+          name: Fumes temperature
+        stove_power:
+          name: Stove power level
+        fan_speed:
+          fan_rpm_offset: 240
+          name: Fan RPM
+        water_temperature:
+          name: Water temperature
+        water_pressure:
+          name: Water pressure
+        memory_address_sensor:
+          memory_location: 0x20
+          memory_address: 0x7d
+          name: Custom Address sensor
+
+Configuration variables:
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+- **room_temperature** (*Optional*): Sensor that reads the stoves ambient room temperature.
+  All options from :ref:`Sensor <config-sensor>`.
+- **fumes_temperature** (*Optional*): Fumes temperature.
+  All options from :ref:`Sensor <config-sensor>`.
+- **stove_power** (*Optional*): Current stove power.
+  All options from :ref:`Sensor <config-sensor>`.
+- **fan_speed** (*Optional*): Current fan speed. The raw value from the stove is multiplied by 10 + ``fan_rpm_offset``.
+
+  - **fan_rpm_offset** (*Optional*, integer): Offset the reported RPM value. Must be between 0 and 255. Defaults to 0.
+  - All other options from :ref:`Sensor <config-sensor>`.
+- **water_temperature** (*Optional*): Internal boiler water termperature.
+  All options from :ref:`Sensor <config-sensor>`.
+- **water_pressure** (*Optional*): Internal boiler water pressure.
+  All options from :ref:`Sensor <config-sensor>`.
+- **memory_address_sensor** (*Optional*): Can be any **memory_location** / **memory_address** you want to track. Usefull
+  when you don't know where the parameter is for your stove is.
+  All options from :ref:`Sensor <config-sensor>`.
+
+
+Numbers
+-------
+
+.. code-block:: yaml
+
+    number:
+      - platform: micronova
+        thermostat_temperature:
+          name: Thermostat temperature
+          step: 0.5
+        power_level:
+          name: Thermostat temperature
+
+Configuration variables:
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+- **thermostat_temperature** (*Optional*): Number that holds the current stove thermostat value.
+   - **step** (*Optional*): Temperature step. This value is used to multiply/devide the raw value when setting/reading the **thermostat_temperature**
+   - All other options from :ref:`Number <config-number>`.
+- **power_level** (*Optional*): Number that sets/reads the requested stove power.
+  All options from :ref:`Number <config-number>`.
+
+.. note::
+
+    Besides **memory_location** and **memory_address** you can specify a specific **memory_write_location** parameter.
+    This parameter is a hex value for the **memory_location** where the new thermostat value must be written.
+
+    - **memory_write_location** (*Optional*): The **memory_location** where to write the new thermostat value.
+
+Buttons
+-------
+
+.. code-block:: yaml
+
+    button:
+      - platform: micronova
+        custom_button:
+          name: Custom button
+          memory_location: 0x20
+          memory_address: 0x7d
+          memory_data: 0x08
+
+Configuration variables:
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+- **custom_button** (*Optional*): Write the hex value **memory_data** to a **memory_location** and **memory_address**
+  All options from :ref:`Button <config-button>`.
+
+.. note::
+
+    Besides **memory_location** and **memory_address** you must specify a specific **memory_data** parameter.
+
+    - **memory_data** (*Required*): The hex value to be written to the **memory_location** and **memory_address**.
+
+Switches
+--------
+
+.. code-block:: yaml
+
+    switch:
+      - platform: micronova
+        stove:
+          name: Stove on/off switch
+
+Configuration variables:
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+- **stove** (*Optional*): Turn the stove on or off. This switch will also reflect the current stove state.
+  If the **stove_state** is "Off" the switch will be off, in all other states, the switch wil be on.
+  All options from :ref:`Switch <config-switch>`.
+
+.. note::
+
+    Besides **memory_location** and **memory_address** you can specify specific **memory_data_on** and **memory_data_off** parameters.
+    These parameters contain the hex value to be written to the **memory_location** and **memory_address** when the switch
+    turns on or off.
+
+    - **memory_data_on** (*Optional*): The data to write when turning the switch on.
+    - **memory_data_off** (*Optional*): The data to write when turning the switch off.
+
+See Also
+--------
+
+- `ridiculouslab micronova <https://www.ridiculouslab.com/arguments/iot/stufa/micronova_en.php>`__
+- `philibertc / micronova_controller  <https://github.com/philibertc/micronova_controller/>`__
+- `eni23 / micronova-controller  <https://github.com/eni23/micronova-controller>`__
+- :ghedit:`Edit`

images/pellet.svg

@@ -0,0 +1 @@
+<svg viewBox="0 0 160 25" id="svg5" xmlns="http://www.w3.org/2000/svg" xmlns:svg="http://www.w3.org/2000/svg"><defs id="defs9"/><path d="M5 0H155a5 5 0 015 5v15a5 5 0 01-5 5H5a5 5 0 01-5-5V5a5 5 0 015-5z" style="fill:#000" id="path2"/><g aria-label="MicroNova" id="component-text" style="font-weight:900;font-size:25px;font-family:Montserrat;letter-spacing:1.1px;fill:#fffffc"><path d="M6.425 21V3.5h4.85l7 11.425h-2.55L22.525 3.5h4.85L27.425 21H22.05L22 11.6h.85L18.2 19.425H15.6L10.75 11.6H11.8V21z" id="path11"/><path d="M31.200012 21V7.325h5.65V21zm2.825-14.775q-1.55.0-2.475-.825-.925-.825-.925-2.05.0-1.225.925-2.05.925-.825 2.475-.825 1.55.0 2.475.775.925.775.925 2 0 1.3-.925 2.15-.925.825-2.475.825z" id="path13"/><path d="m47.800016 21.25q-2.35.0-4.175-.9-1.825-.9-2.875-2.5-1.025-1.625-1.025-3.7t1.025-3.675q1.05-1.6 2.875-2.5t4.175-.9q2.5.0 4.275 1.075t2.45 2.975l-4.375 2.15q-.425-.95-1.05-1.375-.6-.425-1.325-.425-.625.0-1.175.3-.525.3-.85.9-.3.575-.3 1.475t.3 1.5q.325.6.85.9.55.3 1.175.3.725.0 1.325-.425.625-.425 1.05-1.375l4.375 2.15q-.675 1.9-2.45 2.975-1.775 1.075-4.275 1.075z" id="path15"/><path d="M56.925011 21V7.325h5.375v4.125l-.875-1.175q.625-1.6 2-2.4 1.375-.8 3.3-.8v5q-.375-.05-.675-.075-.275-.025-.575-.025-1.275.0-2.1.675-.8.65-.8 2.275V21z" id="path17"/><path d="m76.525018 21.25q-2.325.0-4.125-.9-1.775-.925-2.8-2.525-1.025-1.6-1.025-3.675t1.025-3.675q1.025-1.6 2.8-2.5 1.8-.9 4.125-.9t4.125.9 2.8 2.5q1.025 1.6 1.025 3.675t-1.025 3.675q-1 1.6-2.8 2.525-1.8.9-4.125.9zm0-4.4q.625.0 1.125-.3t.8-.9q.3-.625.3-1.5.0-.9-.3-1.475-.3-.6-.8-.9t-1.125-.3-1.125.3-.8.9q-.3.575-.3 1.475.0.875.3 1.5.3.6.8.9t1.125.3z" id="path19"/><path d="M87.525006 21V3.5h4.85l8.900004 10.65H99.025006V3.5h5.750004V21h-4.850004l-8.9-10.65h2.25V21z" id="path21"/><path d="m115.77503 21.25q-2.325.0-4.125-.9-1.775-.925-2.8-2.525-1.025-1.6-1.025-3.675t1.025-3.675q1.025-1.6 2.8-2.5 1.8-.9 4.125-.9t4.125.9 2.8 2.5q1.025 1.6 1.025 3.675t-1.025 3.675q-1 1.6-2.8 2.525-1.8.9-4.125.9zm0-4.4q.625.0 1.125-.3t.8-.9q.3-.625.3-1.5.0-.9-.3-1.475-.3-.6-.8-.9t-1.125-.3-1.125.3-.8.9q-.3.575-.3 1.475.0.875.3 1.5.3.6.8.9t1.125.3z" id="path23"/><path d="m130.10003 21-5.5-13.675h5.8l4.175 11.1h-2.925l4.45-11.1h5.35l-5.5 13.675z" id="path25"/><path d="m151.19999 21v-2.425l-.4-.65v-4.6q0-1-.625-1.525-.6-.525-1.975-.525-.925.0-1.875.3-.95.275-1.625.775l-1.8-3.725q1.2-.75 2.875-1.15t3.275-.4q3.525.0 5.45 1.575 1.95 1.575 1.95 5V21zm-3.875.25q-1.675.0-2.8-.575t-1.7-1.525q-.575-.975-.575-2.15.0-1.325.675-2.25t2.05-1.4q1.4-.475 3.525-.475h2.85V15.6h-1.95q-.9.0-1.325.3-.4.275-.4.85.0.475.35.8.375.3 1 .3.575.0 1.05-.3.5-.325.725-1l.725 1.675q-.325 1.525-1.375 2.275t-2.825.75z" id="path27"/></g></svg>

index.rst

@@ -397,6 +397,7 @@ Miscellaneous
     Person Sensor (SEN21231), components/sensor/sen21231, sen21231.png
     Kuntze pool sensor, components/sensor/kuntze, kuntze.jpg
     WireGuard, components/wireguard, wireguard_custom_logo.svg
+    MicroNova pellet stove, components/micronova, pellet.svg
 
 
 Motion