Add sun_gtil2 component (for SUN-1000G2 / SUN-2000G2 grid tie inverters) (#4958)

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

CODEOWNERS

@@ -345,6 +345,7 @@ esphome/components/st7789v/* @kbx81
 esphome/components/st7920/* @marsjan155
 esphome/components/substitutions/* @esphome/core
 esphome/components/sun/* @OttoWinter
+esphome/components/sun_gtil2/* @Mat931
 esphome/components/switch/* @esphome/core
 esphome/components/t6615/* @tylermenezes
 esphome/components/tca9548a/* @andreashergert1984

esphome/components/sun_gtil2/__init__.py

@@ -0,0 +1,26 @@
+import esphome.codegen as cg
+import esphome.config_validation as cv
+from esphome.components import uart
+from esphome.const import CONF_ID
+
+CODEOWNERS = ["@Mat931"]
+MULTI_CONF = True
+DEPENDENCIES = ["uart"]
+
+CONF_SUN_GTIL2_ID = "sun_gtil2_id"
+
+sun_gtil2_ns = cg.esphome_ns.namespace("sun_gtil2")
+
+SunGTIL2Component = sun_gtil2_ns.class_("SunGTIL2", cg.Component, uart.UARTDevice)
+
+CONFIG_SCHEMA = cv.Schema(
+    {
+        cv.GenerateID(): cv.declare_id(SunGTIL2Component),
+    }
+).extend(uart.UART_DEVICE_SCHEMA)
+
+
+async def to_code(config):
+    var = cg.new_Pvariable(config[CONF_ID])
+    await cg.register_component(var, config)
+    await uart.register_uart_device(var, config)

esphome/components/sun_gtil2/sensor.py

@@ -0,0 +1,87 @@
+import esphome.codegen as cg
+import esphome.config_validation as cv
+from esphome.components import sensor
+from esphome.const import (
+    DEVICE_CLASS_VOLTAGE,
+    DEVICE_CLASS_POWER,
+    DEVICE_CLASS_TEMPERATURE,
+    ICON_FLASH,
+    UNIT_VOLT,
+    ICON_THERMOMETER,
+    UNIT_WATT,
+    UNIT_CELSIUS,
+    CONF_TEMPERATURE,
+)
+from . import SunGTIL2Component, CONF_SUN_GTIL2_ID
+
+CONF_AC_VOLTAGE = "ac_voltage"
+CONF_DC_VOLTAGE = "dc_voltage"
+CONF_AC_POWER = "ac_power"
+CONF_DC_POWER = "dc_power"
+CONF_LIMITER_POWER = "limiter_power"
+
+CONFIG_SCHEMA = cv.All(
+    cv.Schema(
+        {
+            cv.GenerateID(CONF_SUN_GTIL2_ID): cv.use_id(SunGTIL2Component),
+            cv.Optional(CONF_AC_VOLTAGE): sensor.sensor_schema(
+                unit_of_measurement=UNIT_VOLT,
+                icon=ICON_FLASH,
+                accuracy_decimals=1,
+                device_class=DEVICE_CLASS_VOLTAGE,
+            ),
+            cv.Optional(CONF_DC_VOLTAGE): sensor.sensor_schema(
+                unit_of_measurement=UNIT_VOLT,
+                icon=ICON_FLASH,
+                accuracy_decimals=1,
+                device_class=DEVICE_CLASS_VOLTAGE,
+            ),
+            cv.Optional(CONF_AC_POWER): sensor.sensor_schema(
+                unit_of_measurement=UNIT_WATT,
+                icon=ICON_FLASH,
+                accuracy_decimals=1,
+                device_class=DEVICE_CLASS_POWER,
+            ),
+            cv.Optional(CONF_DC_POWER): sensor.sensor_schema(
+                unit_of_measurement=UNIT_WATT,
+                icon=ICON_FLASH,
+                accuracy_decimals=1,
+                device_class=DEVICE_CLASS_POWER,
+            ),
+            cv.Optional(CONF_LIMITER_POWER): sensor.sensor_schema(
+                unit_of_measurement=UNIT_WATT,
+                icon=ICON_FLASH,
+                accuracy_decimals=1,
+                device_class=DEVICE_CLASS_POWER,
+            ),
+            cv.Optional(CONF_TEMPERATURE): sensor.sensor_schema(
+                unit_of_measurement=UNIT_CELSIUS,
+                icon=ICON_THERMOMETER,
+                accuracy_decimals=1,
+                device_class=DEVICE_CLASS_TEMPERATURE,
+            ),
+        }
+    ).extend(cv.COMPONENT_SCHEMA)
+)
+
+
+async def to_code(config):
+    hub = await cg.get_variable(config[CONF_SUN_GTIL2_ID])
+    if ac_voltage_config := config.get(CONF_AC_VOLTAGE):
+        sens = await sensor.new_sensor(ac_voltage_config)
+        cg.add(hub.set_ac_voltage(sens))
+    if dc_voltage_config := config.get(CONF_DC_VOLTAGE):
+        sens = await sensor.new_sensor(dc_voltage_config)
+        cg.add(hub.set_dc_voltage(sens))
+    if ac_power_config := config.get(CONF_AC_POWER):
+        sens = await sensor.new_sensor(ac_power_config)
+        cg.add(hub.set_ac_power(sens))
+    if dc_power_config := config.get(CONF_DC_POWER):
+        sens = await sensor.new_sensor(dc_power_config)
+        cg.add(hub.set_dc_power(sens))
+    if limiter_power_config := config.get(CONF_LIMITER_POWER):
+        sens = await sensor.new_sensor(limiter_power_config)
+        cg.add(hub.set_limiter_power(sens))
+    if temperature_config := config.get(CONF_TEMPERATURE):
+        sens = await sensor.new_sensor(temperature_config)
+        cg.add(hub.set_temperature(sens))

esphome/components/sun_gtil2/sun_gtil2.cpp

@@ -0,0 +1,135 @@
+#include "sun_gtil2.h"
+#include "esphome/core/log.h"
+
+namespace esphome {
+namespace sun_gtil2 {
+
+static const char *const TAG = "sun_gtil2";
+
+static const double NTC_A = 0.0011591051055979914;
+static const double NTC_B = 0.00022878183547845582;
+static const double NTC_C = 1.0396291358342124e-07;
+static const float PULLUP_RESISTANCE = 10000.0f;
+static const uint16_t ADC_MAX = 1023;  // ADC of the inverter controller, not the ESP
+
+struct SunGTIL2Message {
+  uint16_t sync;
+  uint8_t ac_waveform[277];
+  uint8_t frequency;
+  uint16_t ac_voltage;
+  uint16_t ac_power;
+  uint16_t dc_voltage;
+  uint8_t state;
+  uint8_t unknown1;
+  uint8_t unknown2;
+  uint8_t unknown3;
+  uint8_t limiter_mode;
+  uint8_t unknown4;
+  uint16_t temperature;
+  uint32_t limiter_power;
+  uint16_t dc_power;
+  char serial_number[10];
+  uint8_t unknown5;
+  uint8_t end[39];
+} __attribute__((packed));
+
+static const uint16_t MESSAGE_SIZE = sizeof(SunGTIL2Message);
+
+static_assert(MESSAGE_SIZE == 350, "Expected the message size to be 350 bytes");
+
+void SunGTIL2::setup() { this->rx_message_.reserve(MESSAGE_SIZE); }
+
+void SunGTIL2::loop() {
+  while (this->available()) {
+    uint8_t c;
+    this->read_byte(&c);
+    this->handle_char_(c);
+  }
+}
+
+std::string SunGTIL2::state_to_string_(uint8_t state) {
+  switch (state) {
+    case 0x02:
+      return "Starting voltage too low";
+    case 0x07:
+      return "Working";
+    default:
+      return str_sprintf("Unknown (0x%02x)", state);
+  }
+}
+
+float SunGTIL2::calculate_temperature_(uint16_t adc_value) {
+  if (adc_value >= ADC_MAX || adc_value == 0) {
+    return NAN;
+  }
+
+  float ntc_resistance = PULLUP_RESISTANCE / ((static_cast<float>(ADC_MAX) / adc_value) - 1.0f);
+  double lr = log(double(ntc_resistance));
+  double v = NTC_A + NTC_B * lr + NTC_C * lr * lr * lr;
+  return float(1.0 / v - 273.15);
+}
+
+void SunGTIL2::handle_char_(uint8_t c) {
+  if (this->rx_message_.size() > 1 || c == 0x07) {
+    this->rx_message_.push_back(c);
+  } else if (!this->rx_message_.empty()) {
+    this->rx_message_.clear();
+  }
+  if (this->rx_message_.size() < MESSAGE_SIZE) {
+    return;
+  }
+
+  SunGTIL2Message msg;
+  memcpy(&msg, this->rx_message_.data(), MESSAGE_SIZE);
+  this->rx_message_.clear();
+
+  if (!((msg.end[0] == 0) && (msg.end[38] == 0x08)))
+    return;
+
+  ESP_LOGVV(TAG, "Frequency raw value: %02x", msg.frequency);
+  ESP_LOGVV(TAG, "Unknown values: %02x %02x %02x %02x %02x", msg.unknown1, msg.unknown2, msg.unknown3, msg.unknown4,
+            msg.unknown5);
+
+#ifdef USE_SENSOR
+  if (this->ac_voltage_ != nullptr)
+    this->ac_voltage_->publish_state(__builtin_bswap16(msg.ac_voltage) / 10.0f);
+  if (this->dc_voltage_ != nullptr)
+    this->dc_voltage_->publish_state(__builtin_bswap16(msg.dc_voltage) / 8.0f);
+  if (this->ac_power_ != nullptr)
+    this->ac_power_->publish_state(__builtin_bswap16(msg.ac_power) / 10.0f);
+  if (this->dc_power_ != nullptr)
+    this->dc_power_->publish_state(__builtin_bswap16(msg.dc_power) / 10.0f);
+  if (this->limiter_power_ != nullptr)
+    this->limiter_power_->publish_state(static_cast<int32_t>(__builtin_bswap32(msg.limiter_power)) / 10.0f);
+  if (this->temperature_ != nullptr)
+    this->temperature_->publish_state(calculate_temperature_(__builtin_bswap16(msg.temperature)));
+#endif
+#ifdef USE_TEXT_SENSOR
+  if (this->state_ != nullptr) {
+    this->state_->publish_state(this->state_to_string_(msg.state));
+  }
+  if (this->serial_number_ != nullptr) {
+    std::string serial_number;
+    serial_number.assign(msg.serial_number, 10);
+    this->serial_number_->publish_state(serial_number);
+  }
+#endif
+}
+
+void SunGTIL2::dump_config() {
+#ifdef USE_SENSOR
+  LOG_SENSOR("", "AC Voltage", this->ac_voltage_);
+  LOG_SENSOR("", "DC Voltage", this->dc_voltage_);
+  LOG_SENSOR("", "AC Power", this->ac_power_);
+  LOG_SENSOR("", "DC Power", this->dc_power_);
+  LOG_SENSOR("", "Limiter Power", this->limiter_power_);
+  LOG_SENSOR("", "Temperature", this->temperature_);
+#endif
+#ifdef USE_TEXT_SENSOR
+  LOG_TEXT_SENSOR("", "State", this->state_);
+  LOG_TEXT_SENSOR("", "Serial Number", this->serial_number_);
+#endif
+}
+
+}  // namespace sun_gtil2
+}  // namespace esphome

esphome/components/sun_gtil2/sun_gtil2.h

@@ -0,0 +1,58 @@
+#pragma once
+
+#include "esphome/core/component.h"
+#include "esphome/core/defines.h"
+
+#ifdef USE_SENSOR
+#include "esphome/components/sensor/sensor.h"
+#endif
+#ifdef USE_TEXT_SENSOR
+#include "esphome/components/text_sensor/text_sensor.h"
+#endif
+#include "esphome/components/uart/uart.h"
+
+namespace esphome {
+namespace sun_gtil2 {
+
+class SunGTIL2 : public Component, public uart::UARTDevice {
+ public:
+  float get_setup_priority() const override { return setup_priority::LATE; }
+  void setup() override;
+  void loop() override;
+  void dump_config() override;
+
+#ifdef USE_SENSOR
+  void set_ac_voltage(sensor::Sensor *sensor) { ac_voltage_ = sensor; }
+  void set_dc_voltage(sensor::Sensor *sensor) { dc_voltage_ = sensor; }
+  void set_ac_power(sensor::Sensor *sensor) { ac_power_ = sensor; }
+  void set_dc_power(sensor::Sensor *sensor) { dc_power_ = sensor; }
+  void set_limiter_power(sensor::Sensor *sensor) { limiter_power_ = sensor; }
+  void set_temperature(sensor::Sensor *sensor) { temperature_ = sensor; }
+#endif
+#ifdef USE_TEXT_SENSOR
+  void set_state(text_sensor::TextSensor *text_sensor) { state_ = text_sensor; }
+  void set_serial_number(text_sensor::TextSensor *text_sensor) { serial_number_ = text_sensor; }
+#endif
+
+ protected:
+  std::string state_to_string_(uint8_t state);
+#ifdef USE_SENSOR
+  sensor::Sensor *ac_voltage_{nullptr};
+  sensor::Sensor *dc_voltage_{nullptr};
+  sensor::Sensor *ac_power_{nullptr};
+  sensor::Sensor *dc_power_{nullptr};
+  sensor::Sensor *limiter_power_{nullptr};
+  sensor::Sensor *temperature_{nullptr};
+#endif
+#ifdef USE_TEXT_SENSOR
+  text_sensor::TextSensor *state_{nullptr};
+  text_sensor::TextSensor *serial_number_{nullptr};
+#endif
+
+  float calculate_temperature_(uint16_t adc_value);
+  void handle_char_(uint8_t c);
+  std::vector<uint8_t> rx_message_;
+};
+
+}  // namespace sun_gtil2
+}  // namespace esphome

esphome/components/sun_gtil2/text_sensor.py

@@ -0,0 +1,31 @@
+import esphome.codegen as cg
+import esphome.config_validation as cv
+from esphome.components import text_sensor
+from esphome.const import CONF_STATE
+from . import SunGTIL2Component, CONF_SUN_GTIL2_ID
+
+CONF_SERIAL_NUMBER = "serial_number"
+
+CONFIG_SCHEMA = cv.All(
+    cv.Schema(
+        {
+            cv.GenerateID(CONF_SUN_GTIL2_ID): cv.use_id(SunGTIL2Component),
+            cv.Optional(CONF_STATE): text_sensor.text_sensor_schema(
+                text_sensor.TextSensor
+            ),
+            cv.Optional(CONF_SERIAL_NUMBER): text_sensor.text_sensor_schema(
+                text_sensor.TextSensor
+            ),
+        }
+    ).extend(cv.COMPONENT_SCHEMA)
+)
+
+
+async def to_code(config):
+    hub = await cg.get_variable(config[CONF_SUN_GTIL2_ID])
+    if state_config := config.get(CONF_STATE):
+        sens = await text_sensor.new_text_sensor(state_config)
+        cg.add(hub.set_state(sens))
+    if serial_number_config := config.get(CONF_SERIAL_NUMBER):
+        sens = await text_sensor.new_text_sensor(serial_number_config)
+        cg.add(hub.set_serial_number(sens))

tests/components/sun_gtil2/test.esp32-c3-idf.yaml

@@ -0,0 +1,44 @@
+uart:
+  - id: control_to_display
+    rx_pin:
+      number: 5
+    baud_rate: 9600
+
+sun_gtil2:
+  uart_id: control_to_display
+
+sensor:
+  - platform: sun_gtil2
+    temperature:
+      id: gtil_temperature
+      name: "Heatsink Temperature"
+      filters:
+        - throttle_average: 30s
+    dc_voltage:
+      id: gtil_dc_voltage
+      name: "DC Voltage"
+      filters:
+        - throttle_average: 30s
+    ac_voltage:
+      id: gtil_ac_voltage
+      name: "AC Voltage"
+      filters:
+        - throttle_average: 30s
+    ac_power:
+      id: gtil_ac_power
+      name: "AC Power"
+    dc_power:
+      id: gtil_dc_power
+      name: "DC Power"
+    limiter_power:
+      id: gtil_limiter_power
+      internal: true
+
+text_sensor:
+  - platform: sun_gtil2
+    state:
+      id: gtil_state
+      name: "State"
+    serial_number:
+      id: gtil_serial_number
+      internal: true

tests/components/sun_gtil2/test.esp32-c3.yaml

@@ -0,0 +1,44 @@
+uart:
+  - id: control_to_display
+    rx_pin:
+      number: 5
+    baud_rate: 9600
+
+sun_gtil2:
+  uart_id: control_to_display
+
+sensor:
+  - platform: sun_gtil2
+    temperature:
+      id: gtil_temperature
+      name: "Heatsink Temperature"
+      filters:
+        - throttle_average: 30s
+    dc_voltage:
+      id: gtil_dc_voltage
+      name: "DC Voltage"
+      filters:
+        - throttle_average: 30s
+    ac_voltage:
+      id: gtil_ac_voltage
+      name: "AC Voltage"
+      filters:
+        - throttle_average: 30s
+    ac_power:
+      id: gtil_ac_power
+      name: "AC Power"
+    dc_power:
+      id: gtil_dc_power
+      name: "DC Power"
+    limiter_power:
+      id: gtil_limiter_power
+      internal: true
+
+text_sensor:
+  - platform: sun_gtil2
+    state:
+      id: gtil_state
+      name: "State"
+    serial_number:
+      id: gtil_serial_number
+      internal: true

tests/components/sun_gtil2/test.esp32-idf.yaml

@@ -0,0 +1,44 @@
+uart:
+  - id: control_to_display
+    rx_pin:
+      number: 16
+    baud_rate: 9600
+
+sun_gtil2:
+  uart_id: control_to_display
+
+sensor:
+  - platform: sun_gtil2
+    temperature:
+      id: gtil_temperature
+      name: "Heatsink Temperature"
+      filters:
+        - throttle_average: 30s
+    dc_voltage:
+      id: gtil_dc_voltage
+      name: "DC Voltage"
+      filters:
+        - throttle_average: 30s
+    ac_voltage:
+      id: gtil_ac_voltage
+      name: "AC Voltage"
+      filters:
+        - throttle_average: 30s
+    ac_power:
+      id: gtil_ac_power
+      name: "AC Power"
+    dc_power:
+      id: gtil_dc_power
+      name: "DC Power"
+    limiter_power:
+      id: gtil_limiter_power
+      internal: true
+
+text_sensor:
+  - platform: sun_gtil2
+    state:
+      id: gtil_state
+      name: "State"
+    serial_number:
+      id: gtil_serial_number
+      internal: true

tests/components/sun_gtil2/test.esp32.yaml

@@ -0,0 +1,44 @@
+uart:
+  - id: control_to_display
+    rx_pin:
+      number: 16
+    baud_rate: 9600
+
+sun_gtil2:
+  uart_id: control_to_display
+
+sensor:
+  - platform: sun_gtil2
+    temperature:
+      id: gtil_temperature
+      name: "Heatsink Temperature"
+      filters:
+        - throttle_average: 30s
+    dc_voltage:
+      id: gtil_dc_voltage
+      name: "DC Voltage"
+      filters:
+        - throttle_average: 30s
+    ac_voltage:
+      id: gtil_ac_voltage
+      name: "AC Voltage"
+      filters:
+        - throttle_average: 30s
+    ac_power:
+      id: gtil_ac_power
+      name: "AC Power"
+    dc_power:
+      id: gtil_dc_power
+      name: "DC Power"
+    limiter_power:
+      id: gtil_limiter_power
+      internal: true
+
+text_sensor:
+  - platform: sun_gtil2
+    state:
+      id: gtil_state
+      name: "State"
+    serial_number:
+      id: gtil_serial_number
+      internal: true

tests/components/sun_gtil2/test.esp8266.yaml

@@ -0,0 +1,44 @@
+uart:
+  - id: control_to_display
+    rx_pin:
+      number: 5
+    baud_rate: 9600
+
+sun_gtil2:
+  uart_id: control_to_display
+
+sensor:
+  - platform: sun_gtil2
+    temperature:
+      id: gtil_temperature
+      name: "Heatsink Temperature"
+      filters:
+        - throttle_average: 30s
+    dc_voltage:
+      id: gtil_dc_voltage
+      name: "DC Voltage"
+      filters:
+        - throttle_average: 30s
+    ac_voltage:
+      id: gtil_ac_voltage
+      name: "AC Voltage"
+      filters:
+        - throttle_average: 30s
+    ac_power:
+      id: gtil_ac_power
+      name: "AC Power"
+    dc_power:
+      id: gtil_dc_power
+      name: "DC Power"
+    limiter_power:
+      id: gtil_limiter_power
+      internal: true
+
+text_sensor:
+  - platform: sun_gtil2
+    state:
+      id: gtil_state
+      name: "State"
+    serial_number:
+      id: gtil_serial_number
+      internal: true

tests/components/sun_gtil2/test.rp2040.yaml

@@ -0,0 +1,44 @@
+uart:
+  - id: control_to_display
+    rx_pin:
+      number: 5
+    baud_rate: 9600
+
+sun_gtil2:
+  uart_id: control_to_display
+
+sensor:
+  - platform: sun_gtil2
+    temperature:
+      id: gtil_temperature
+      name: "Heatsink Temperature"
+      filters:
+        - throttle_average: 30s
+    dc_voltage:
+      id: gtil_dc_voltage
+      name: "DC Voltage"
+      filters:
+        - throttle_average: 30s
+    ac_voltage:
+      id: gtil_ac_voltage
+      name: "AC Voltage"
+      filters:
+        - throttle_average: 30s
+    ac_power:
+      id: gtil_ac_power
+      name: "AC Power"
+    dc_power:
+      id: gtil_dc_power
+      name: "DC Power"
+    limiter_power:
+      id: gtil_limiter_power
+      internal: true
+
+text_sensor:
+  - platform: sun_gtil2
+    state:
+      id: gtil_state
+      name: "State"
+    serial_number:
+      id: gtil_serial_number
+      internal: true