💻 Programming

There are two main programming methods supported and tested with the Smart Plant:

• ESPHome

• Arduino

In both scenarios, and if you are using the USB port or the Serial port for programming it, you will first need to enter the board into flashing mode: press and hold the Flash pushbutton while you reset the board (pressing once the Reset pushbutton).

Caution

When flashing the board, make sure its only powered by the USB/Serial port.

ESPHome

ESPHome is a well known platform for programming ESP-based devices with a very little effort. It is configured via YAML files and supports a wide range of functionalities and sensors.

Hint

For using ESPHome, and all its funcionalities, you need to have a Home Assistant instance running in the same network as your Smart Plant.

The Smart Plant comes raw, without any firmware by default, therefore, you will need to flash it for first time. There are many ways to flash your ESPHome device (locally, ESPHome Web), but the one I strongly recommend is the one through the ESPHome Add-on for Home Assistant:

Error

For the last months, the ESPHome Web web has been having some issues when trying to flash ESP32-S2 modules. Therefore the best way to flash it for first time is with the ESPHome HA (Home Assistant) add-on running on a Raspberry Pi and the Smart Powermeter connected to the RPi.

1. Make sure your ESPHome Add-on for HA is up to date and working.

2. Add a new device, enter the name you want (like Smart-Plant), and skip the next step.

3. Select the ESP32-S2 as the device type, skip the last step (installation). You will have created a provisional first configuration YAML file.

4. Open the recently created file and replace the content with the example configuration smart-plant.yaml

Note

You might need to keep the encription keys OTA and API

substitutions:
  device_name: "smart-plant"
  friendly_name: "Smart Plant"
  project_name: "smart.plant"
  project_version: "2.2"
  ap_pwd: "smartplant"
  # IANA timezone string — find yours at https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
  timezone: "UTC"

esphome:
  name: "${device_name}"
  name_add_mac_suffix: true
  project:
    name: "${project_name}"
    version: "${project_version}"
  # Start the main loop immediately after boot. SNTP sync is handled
  # asynchronously via on_time_sync below, which triggers a display refresh
  # the moment time becomes valid — no fixed delay needed.
  on_boot:
    priority: 600
    then:
      - script.execute: consider_deep_sleep


esp32:
  board: esp32-s2-saola-1
  framework:
    type: arduino

# Enable logging
logger:

api:

# Enable MQTT for deep sleep compatibility instead of the api if you preffer to use MQTT 
# mqtt:
#   broker: !secret mqtt_broker
#   discovery: true
#   discovery_retain: true
#   birth_message:
#   will_message:
#   log_topic:

# Enable Over The Air updates
ota:
  - platform: esphome
  
#Public location of this yaml file
dashboard_import:
  package_import_url: github://JGAguado/Smart_Plant/docs/source/files/configuration.yaml@V2R1
  import_full_config: false

# Enable fallback hotspot (captive portal) in case wifi connection fails
captive_portal:

improv_serial:

wifi:
  fast_connect: true
  power_save_mode: none  # Disable WiFi modem sleep for faster reconnection on wake
  ap:
    password: "${ap_pwd}"


i2c:
  scl: GPIO34
  sda: GPIO33
  scan: false
  id: bus_a

spi:
  clk_pin:  GPIO12
  mosi_pin: GPIO11
    
image:
  - file: "https://smart-plant.readthedocs.io/en/v2r1/_images/Lemon_tree_label_page_1.png"
    id: page_1_background
    type: binary
    invert_alpha: true

font:
  - file: "gfonts://Audiowide"
    id: font_title
    size: 20
  - file: "gfonts://Audiowide"
    id: font_subtitle
    size: 15
  - file: "gfonts://Audiowide"
    id: font_parameters
    size: 15
  - file: 'gfonts://Material+Symbols+Outlined'
    id: font_icon
    size: 20
    glyphs:
      - "\U0000ebdc" # battery empty
      - "\U0000ebd9" # battery 1 bar
      - "\U0000ebe0" # battery 2 bar
      - "\U0000ebdd" # battery 3 bar
      - "\U0000ebe2" # battery 4 bar
      - "\U0000ebd4" # battery 5 bar
      - "\U0000e1a4" # battery full
      - "\U0000e627" # sync

time:
  - platform: sntp
    id: esptime
    timezone: "${timezone}"
    servers:
      - "162.159.200.1"    # Cloudflare NTP (stable anycast IP — no DNS needed)
      - "216.239.35.0"     # Google NTP
      - "pool.ntp.org"     # fallback
    on_time_sync:
      then:
        - component.update: my_display

switch:
  - platform: gpio
    pin: GPIO4
    id: exc
    icon: "mdi:power"
    restore_mode: ALWAYS_ON
    internal: true  
    
    
sensor:    

  # Battery level sensor    
  - platform: max17043
    id: max17043_id
    battery_voltage:
      id: batvolt      
      name: "${friendly_name} Battery voltage"
      internal: true
      force_update: true
    battery_level:
      id: batpercent
      name: "${friendly_name} Battery"
      force_update: true

  # Temperature and humidity sensor
  - platform: aht10
    variant: AHT20 
    i2c_id: bus_a
    temperature:
      name: "${friendly_name} Temperature"
      id: temp
      icon: "mdi:thermometer"
      device_class: temperature
      force_update: true
    humidity:
      name: "${friendly_name} Air Humidity"
      id: hum
      icon: "mdi:water-percent"
      device_class: humidity
      force_update: true
    update_interval: 3s

  # Light sensor
  - platform: veml7700
    address: 0x10
    update_interval: 3s
    ambient_light: 
      name: "${friendly_name} Ambient light"
      id: light
      icon: "mdi:white-balance-sunny"
      device_class: illuminance
      force_update: true
    actual_gain:
      name: "Actual gain"
      internal: true
        
  # Capacitive soil moisture sensor
  - platform: adc
    pin: GPIO1
    name: "${friendly_name} Soil Moisture"
    id : soil
    # In order to have proper mapping in HA
    device_class: moisture
    icon: "mdi:cup-water"
    update_interval: 3s
    unit_of_measurement: "%"
    attenuation: 12db
    force_update: true
    filters:
    - median:
        window_size: 5
        send_every: 5

    - calibrate_linear:
        - 1.25 -> 100.00
        - 2.8 -> 0.00
    - lambda: if (x < 1) return 0; else if (x > 100) return 100; return (x);
    accuracy_decimals: 0

display:
  - platform: waveshare_epaper
    cs_pin: GPIO10
    dc_pin: GPIO13
    busy_pin: GPIO14
    reset_pin: GPIO15
    rotation: 270
    model: 2.90inv2
    id: my_display
    update_interval: never
    full_update_every: 1
    pages: 
      - id: page1
        lambda: |-
          #define H_LEFT_MARGIN 4
          #define H_RIGHT_MARGIN 280
          #define H_CENTER 128 
          #define V_WEATHER 0
          #define V_CLOCK 1
          #define V_WIFI 30
          #define V_VOLTAGE 60
          #define V_BATTERY  90
          
          it.image(0, 0, id(page_1_background));
          
          // // Battery
          float battery_perc = id(batpercent).state;
          int battery_range = battery_perc / 16 ;
          battery_range = (battery_range > 6) ? 6 : battery_range;
          battery_range = (battery_range < 0)  ?  0 : battery_range;
          
          const char* battery_icon_map[] = {
            "\U0000ebdc", // battery empty
            "\U0000ebd9", // battery 1 bar
            "\U0000ebe0", // battery 2 bar
            "\U0000ebdd", // battery 3 bar
            "\U0000ebe2", // battery 4 bar
            "\U0000ebd4", // battery 5 bar
            "\U0000e1a4"  // battery full
          };

          it.printf(278, 1, id(font_icon), TextAlign::TOP_LEFT, battery_icon_map[battery_range]);
          it.printf(278, 1, id(font_subtitle), TextAlign::TOP_RIGHT, 
          "%3.0f%%", battery_perc);
          
          // Date — guard against SNTP not yet synced (avoids displaying 1970)
          auto now = id(esptime).now();
          if (now.is_valid()) {
            it.strftime(278, 18, id(font_subtitle), TextAlign::TOP_RIGHT,
            "%H:%M %d/%m", now);
          } else {
            it.printf(278, 18, id(font_subtitle), TextAlign::TOP_RIGHT, "--:-- --/--");
          }
          it.printf(278, 18, id(font_icon), TextAlign::TOP_LEFT, "\U0000e627");


          // Parameters
          // Drawing the marker over the gauge
          float pi = 3.141592653589793;
          float alpha = 4.71238898038469; // Defined as the gauge angle in radians (270deg)
          float beta = 2*pi - alpha;
          int radius = 22;              // Radius of the gauge in pixels
          int thick = 7;                // Size of the marker 
          
          // *** Moisture ***
          int min_range = 0; 
          int max_range = 100;
          int xc = 80;
          int yc = 50;
          
          float measured = id(soil).state;
          
          if (measured < min_range) {
            measured = min_range;
          } 
          if (measured > max_range) {
            measured = max_range;
          } 
          
          float val = (measured - min_range) / abs(max_range - min_range) * alpha;
          
          int x0 = static_cast<int>(xc + radius + radius * cos(pi / 2 + beta / 2 + val));
          int y0 = static_cast<int>(yc + radius + radius * sin(pi / 2 + beta / 2 + val));
          int x1 = static_cast<int>(xc + radius + (radius+thick) * cos(pi / 2 + beta / 2 + val + 0.1));
          int y1 = static_cast<int>(yc + radius + (radius+thick) * sin(pi / 2 + beta / 2 + val + 0.1));
          int x2 = static_cast<int>(xc + radius + (radius+thick) * cos(pi / 2 + beta / 2 + val - 0.1));
          int y2 = static_cast<int>(yc + radius + (radius+thick) * sin(pi / 2 + beta / 2 + val - 0.1));
          it.line(x0, y0, x1, y1);
          it.line(x1, y1, x2, y2);
          it.line(x2, y2, x0, y0);
          
          it.printf(xc + radius, yc + 1.7*radius, id(font_parameters), TextAlign::TOP_CENTER, 
          "%.0f%%", id(soil).state);  
          
          // *** Light ***
          min_range = 0; 
          max_range = 3775;
          xc = 134;
          yc = 70;
          
          measured = id(light).state;
          
          if (measured < min_range) {
            measured = min_range;
          } 
          if (measured > max_range) {
            measured = max_range;
          } 
          
          val = (measured - min_range) / abs(max_range - min_range) * alpha;        
          x0 = static_cast<int>(xc + radius + radius * cos(pi / 2 + beta / 2 + val));
          y0 = static_cast<int>(yc + radius + radius * sin(pi / 2 + beta / 2 + val));
          x1 = static_cast<int>(xc + radius + (radius+thick) * cos(pi / 2 + beta / 2 + val + 0.1));
          y1 = static_cast<int>(yc + radius + (radius+thick) * sin(pi / 2 + beta / 2 + val + 0.1));
          x2 = static_cast<int>(xc + radius + (radius+thick) * cos(pi / 2 + beta / 2 + val - 0.1));
          y2 = static_cast<int>(yc + radius + (radius+thick) * sin(pi / 2 + beta / 2 + val - 0.1));
          it.line(x0, y0, x1, y1);
          it.line(x1, y1, x2, y2);
          it.line(x2, y2, x0, y0);
          
          it.printf(xc + radius, yc + 1.7*radius, id(font_parameters), TextAlign::TOP_CENTER, 
          "%.0flx", id(light).state);  
          
          
          // *** Temperature ***
          min_range = -10; 
          max_range = 50;
          xc = 188;
          yc = 50;
          
          measured = id(temp).state;
          
          if (measured < min_range) {
            measured = min_range;
          } 
          if (measured > max_range) {
            measured = max_range;
          } 
          
          val = (measured - min_range) / abs(max_range - min_range) * alpha;        
          x0 = static_cast<int>(xc + radius + radius * cos(pi / 2 + beta / 2 + val));
          y0 = static_cast<int>(yc + radius + radius * sin(pi / 2 + beta / 2 + val));
          x1 = static_cast<int>(xc + radius + (radius+thick) * cos(pi / 2 + beta / 2 + val + 0.1));
          y1 = static_cast<int>(yc + radius + (radius+thick) * sin(pi / 2 + beta / 2 + val + 0.1));
          x2 = static_cast<int>(xc + radius + (radius+thick) * cos(pi / 2 + beta / 2 + val - 0.1));
          y2 = static_cast<int>(yc + radius + (radius+thick) * sin(pi / 2 + beta / 2 + val - 0.1));
          it.line(x0, y0, x1, y1);
          it.line(x1, y1, x2, y2);
          it.line(x2, y2, x0, y0);
          
          it.printf(xc + radius, yc + 1.7*radius, id(font_parameters), TextAlign::TOP_CENTER, 
          "%.0f°C", id(temp).state);     
        

          // *** Humidity ***
          min_range = 20; 
          max_range = 80;
          xc = 242;
          yc = 70;
          
          measured = id(hum).state;
          
          if (measured < min_range) {
            measured = min_range;
          } 
          if (measured > max_range) {
            measured = max_range;
          } 
          
          val = (measured - min_range) / abs(max_range - min_range) * alpha;        
          x0 = static_cast<int>(xc + radius + radius * cos(pi / 2 + beta / 2 + val));
          y0 = static_cast<int>(yc + radius + radius * sin(pi / 2 + beta / 2 + val));
          x1 = static_cast<int>(xc + radius + (radius+thick) * cos(pi / 2 + beta / 2 + val + 0.1));
          y1 = static_cast<int>(yc + radius + (radius+thick) * sin(pi / 2 + beta / 2 + val + 0.1));
          x2 = static_cast<int>(xc + radius + (radius+thick) * cos(pi / 2 + beta / 2 + val - 0.1));
          y2 = static_cast<int>(yc + radius + (radius+thick) * sin(pi / 2 + beta / 2 + val - 0.1));
          it.line(x0, y0, x1, y1);
          it.line(x1, y1, x2, y2);
          it.line(x2, y2, x0, y0);
          
          it.printf(xc + radius, yc + 1.7*radius, id(font_parameters), TextAlign::TOP_CENTER, 
          "%.0f%%", id(hum).state);      
          
deep_sleep:
  id: deep_sleep_control
  # run_duration: 5s
  sleep_duration: 1h

script:
  - id: consider_deep_sleep
    mode: queued
    then:
      - delay: 5s
      - component.update: my_display   
      - delay: 5s           
      - if:
          condition:
            sensor.in_range:
              id: batpercent
              above: 95
          then:
            - deep_sleep.prevent: deep_sleep_control 
          else:
            - switch.turn_off: exc              # Cut sensor power before sleep
            - max17043.sleep_mode: max17043_id  # Fuel gauge low-power mode
            - deep_sleep.enter: deep_sleep_control 

      - delay: 25s
      - script.execute: consider_deep_sleep

Important

Note that with this example code, the Smart Plant enters into deep-sleep mode if the battery level is under 95% (see consider_deep_sleep script at the end of the file), so be aware that if you want to flash it OTA, make sure the battery is fully charged or the Smart Plant powered via USB-C.

Note

The Smart Plant integrates a battery gauge sensor (MAX17043/MAX17048). ESPHome includes a native max17043 component — no external_components are needed. The example configuration above already uses it. The native component also provides a sleep_mode action used in the consider_deep_sleep script to put the fuel gauge into low-power mode before entering deep sleep.

Note

Lemon_tree_label_page_1.png is the background image that will be displayed on the e-paper. For having always a styled background image, I made a python script that generates the image of the plant, the title and the parameter gauges out of a JSON config file. Alternativelly, you can use any photo editor of your choice, but keep in mind the display size (296x128 pixel) and the center of each gauges (indicated in the YAML code). In this example, it is obtained from an URL, but you can upload yours locally following the ESPHome guide

5. Click on install, make sure that the the board is connected via the USB-C (and into flashing mode ) to the device running the Home Assistant (in my case a Raspberry Pi) before selecting the mode of installation.

6. Select the Serial port and let it run, it might take some minutes.

7. Once it’s done, you will have to exit the flashing mode: press the Reset pushbutton once.

Now, your ESPHome-based Smart Plant should be ready to log data and stream it to your Home Assistant. Note that the current configuration is just an example and you can customize it at your will, including the calibration.

Tip

A very easy way to upload and copy files (code or even images) into your ESPHome folder hosted in your HA instance is with the help of the Visual Studio Code integration for HA. This way you can just drag and drop the files over the folder on the Home Assistant’s Visual Studio Code navigation panel on your left.

Flash Tools

If you want to deploy an ESPHome already compiled .bin image, you can use Espressif’s official Flash Download Tools to upload it into your Smart Powermeter. As an example (and test) you can use this smart-areca-v2r1-offline.bin image with the address 0x0, make sure DoNotChgBin is checked:

Arduino

If you are still interested in programming directly with the Arduino IDE, the procedure is no different than with any other ESP32 devices:

1. Open the Arduino IDE and go to File -> Preferences option.

2. Add to the Additional Boards Manager URSLs the url:

https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json

3. Close the preferences and open in the menu Tools -> Board -> Boards Manager.

4. Search for esp32 and install it. This might take some time.

5. Now you can select the board ESP32 Dev Module as the target board. Leave the rest of parameters by default.

6. Select the correct port and remember to enter the board into flashing mode before uploading the sketch.

Tip

Remember to check out the full Pinout