diff --git a/components/images/pylontech.jpg b/components/images/pylontech.jpg new file mode 100644 index 000000000..06624cd9a Binary files /dev/null and b/components/images/pylontech.jpg differ diff --git a/components/images/rj45_pinout.jpg b/components/images/rj45_pinout.jpg new file mode 100644 index 000000000..ce898adeb Binary files /dev/null and b/components/images/rj45_pinout.jpg differ diff --git a/components/pylontech.rst b/components/pylontech.rst new file mode 100644 index 000000000..547c85182 --- /dev/null +++ b/components/pylontech.rst @@ -0,0 +1,197 @@ +Pylontech Battery +================= + +.. seo:: + :description: Instructions for setting up Pylontech Battery in ESPHome. + :image: pylontech.jpg + +The Pylontech component allows you to pull data from Pylontech Batteries into ESPHome. +It uses :ref:`UART ` for communication. + +Once configured, you can use sensors as described below for your projects. + +.. figure:: images/pylontech.jpg + :align: center + :width: 50.0% + + Pylontech Batteries + +Hardware Setup +-------------- + +You can connect to Pylontech Batteries using the port labeled "Console". +Any connections via CAN or RS485 (e.g. to an inverter) are untouched and remain functional. + +The console port offers a RS232 interface using a RJ10 or RJ45 connector. +The voltage levels are *not* TTL-compatible. A RS232 transceiver must be placed between the Batteries and the ESPHome device. +MAX3232-based transceivers have been tested and work well. + +If you have multiple batteries you need to connect to the master battery's console port. + +.. list-table:: Pylontech RJ45 Console Port (US2000C, US3000C) + :header-rows: 1 + + * - RJ45 Pin + - Function + - Connect to + * - 3 + - Pylontech TX + - ESPHome RX via transceiver + * - 6 + - Pylontech RX + - ESPHome TX via transceiver + * - 8 + - GND + - GND + +.. figure:: images/rj45_pinout.jpg + :align: center + :width: 70.0% + + RJ45 pinout + +.. list-table:: Pylontech RJ10 Console Pinout (US2000B) + :header-rows: 1 + + * - RJ410 Pin + - Function + - Connect to + * - 2 + - Pylontech RX + - ESPHome TX via transceiver + * - 3 + - Pylontech TX + - ESPHome RX via transceiver + * - 4 + - GND + - GND + +Component/Hub +------------- + +.. code-block:: yaml + + # Example configuration entry + pylontech: + + +Configuration variables: +~~~~~~~~~~~~~~~~~~~~~~~~ + +- **id** (**Required**, :ref:`config-id`): The id to use for this Pylontech component. +- **uart_id** (*Optional*): The uart Bus ID +- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. + +Sensor +------ + +All values are reported for every Pylontech battery individually. + +.. code-block:: yaml + + # Example configuration entry + sensor: + - platform: pylontech + battery: 1 + + voltage: + name: "Battery1 Voltage" + current: + name: "Battery1 Current" + coulomb: + name: "Battery1 State of Charge" + +Configuration variables: +~~~~~~~~~~~~~~~~~~~~~~~~ + +- **pylontech_id** (*Optional*): Manually specify the ID of the pylontech instance if there are multiple. +- **battery** (**Required**): Which battery to monitor. 1 stands for the main battery, 2..6 for child batteries. +- **voltage** (*Optional*): Voltage of the battery. All options from :ref:`Sensor `. +- **current** (*Optional*): Current flowing into the battery. Negative when discharging. All options from :ref:`Sensor `. +- **coulomb** (*Optional*): State of Charge in percent. All options from :ref:`Sensor `. +- **temperature** (*Optional*): Temperature. All options from :ref:`Sensor `. +- **temperature_low** (*Optional*): Historic minimum temperature. All options from :ref:`Sensor `. +- **temperature_high** (*Optional*): Historic maximum temperature. All options from :ref:`Sensor `. +- **voltage_low** (*Optional*): Historic minimum voltage. All options from :ref:`Sensor `. +- **voltage_high** (*Optional*): Historic maximum voltage. All options from :ref:`Sensor `. +- **mos_temperature** (*Optional*): Temperature of the mosfets. All options from :ref:`Sensor `. + +Text Sensor +----------- + +.. code-block:: yaml + + # Example configuration entry + text_sensor: + - platform: pylontech + pylontech_id: pylontech0 + battery: 1 + + base_state: + id: bat1_base_state + name: "Battery1 Base State" + + +Configuration variables: +~~~~~~~~~~~~~~~~~~~~~~~~ + +- **pylontech_id** (**Optional**): Manually specify the ID of the pylontech instance if there are multiple. +- **battery** (**Required**): Which battery to monitor. 1 stands for the main battery, 2..6 for child batteries. +- **base_state** (*Optional*): Base state. Usually reads ``Dischg``, ``Charge`` or ``Idle``. All options from :ref:`Text Sensor `. +- **voltage_state** (*Optional*): Voltage state. Usually reads ``Normal``. All options from :ref:`Text Sensor `. +- **current_state** (*Optional*): Current state. Usually reads ``Normal``. All options from :ref:`Text Sensor `. +- **temperature_state** (*Optional*): Temperature state. Usually reads ``Normal``. All options from :ref:`Text Sensor `. + +Energy Monitoring +----------------- + +By combining :doc:`template sensors ` and :doc:`integration sensors ` +one can monitor the energy flowing into and out of all batteries combined, ready for `Homeassistant Energy Monitoring `__. + +.. code-block:: yaml + + sensor: + - platform: template + id: pylontech_power + name: "Pylontech power" + unit_of_measurement: W + lambda: |- + auto pwr1 = id(bat1_voltage).state * id(bat1_current).state; + auto pwr2 = id(bat2_voltage).state * id(bat2_current).state; + auto pwr = pwr1 + pwr2; + id(combined_charge_power).publish_state(max(pwr, 0.0f)); + id(combined_discharge_power).publish_state(max(-pwr, 0.0f)); + return pwr; + update_interval: 5s + device_class: power + state_class: measurement + + - platform: template + id: combined_charge_power + + - platform: template + id: combined_discharge_power + + - platform: integration + name: "Pylontech charging" + sensor: combined_charge_power + time_unit: h + state_class: total_increasing + device_class: energy + unit_of_measurement: "Wh" + + - platform: integration + name: "Pylontech discharging" + sensor: combined_discharge_power + time_unit: h + state_class: total_increasing + device_class: energy + unit_of_measurement: "Wh" + +See Also +-------- + +- `Pylontech-Battery-Monitoring `__ +- `nodered-pylontech-console-reader `__ +- :ref:`uart` +- :ghedit:`Edit` diff --git a/images/pylontech.jpg b/images/pylontech.jpg new file mode 100644 index 000000000..87925d645 Binary files /dev/null and b/images/pylontech.jpg differ diff --git a/index.rst b/index.rst index f35cbc085..043912f93 100644 --- a/index.rst +++ b/index.rst @@ -511,6 +511,7 @@ Miscellaneous Hydreon Rain Sensor Binary Sensor, components/binary_sensor/hydreon_rgxx, hydreon_rg9.jpg Modbus Binary Sensor, components/binary_sensor/modbus_controller, modbus.png PipSolar - compatible PV Inverter, components/pipsolar, pipsolar.jpg + Pylontech Batteries, components/pylontech, pylontech.jpg Qwiic PIR Motion, components/binary_sensor/qwiic_pir, qwiic_pir.jpg Remote Receiver, components/remote_receiver, remote.svg, dark-invert Resol VBus, components/vbus, resol_deltasol_bs_plus.jpg