Skip to main content

ESPHome Hello World

A minimal starting point for writing your own ESPHome firmware for Kamoji, instead of building on the production configuration described in Firmware Architecture. This is the smallest config that boots Kamoji's screen, turns on its backlight, and draws "Hello World" on the display — a base to build your own project from.

ESPHome version

This config uses the mipi_spi display platform and LVGL, both relatively recent additions to ESPHome. If you hit compile errors, try the same ESPHome version pinned for the production firmware (see Building from Source) rather than whatever esphome resolves to by default.

Prerequisites​

The config​

Download kamojihelloworld.yaml

substitutions:
  name: kamoji-hello-world
  friendly_name: "Kamoji Hello World"

  # ST7789 LCD Screen (SPI) for Kamoji Hardware
  LCD_CLK_PIN: "12"
  LCD_MOSI_PIN: "11"
  LCD_DC_PIN: "14"
  LCD_RESET_PIN: "10"
  LCD_BACKLIGHT_PIN: "13"
  LCD_SPI_DATA_RATE: "80MHz"

  LCD_WIDTH: "240"
  LCD_HEIGHT: "240"
  LCD_HEIGHT_OFFSET: "80"
  LCD_ROTATION: "180"

esphome:
  name: ${name}
  friendly_name: ${friendly_name}
  on_boot:
    priority: 800.0
    then:
      - light.turn_on:
          id: lcd_backlight
          brightness: 100%

esp32:
  board: esp32-s3-devkitc-1
  variant: esp32s3
  flash_size: 16MB
  framework:
    type: esp-idf
    sdkconfig_options:
      CONFIG_SPIRAM_MODE_OCT: "y"
      CONFIG_SPIRAM_MODE_QUAD: "n"
      CONFIG_SPIRAM_SPEED_80M: "y"
      CONFIG_ESP_DEFAULT_CPU_FREQ_MHZ_240: "y"

psram:
  mode: octal
  speed: 80MHz

logger:
  level: DEBUG

output:
  - platform: ledc
    id: backlight_output
    pin: ${LCD_BACKLIGHT_PIN}

light:
  - platform: monochromatic
    id: lcd_backlight
    name: "LCD Backlight"
    output: backlight_output
    restore_mode: ALWAYS_ON

spi:
  id: lcd_spi
  clk_pin: ${LCD_CLK_PIN}
  mosi_pin: ${LCD_MOSI_PIN}
  interface: spi2

display:
  - platform: mipi_spi
    id: lcd_display
    model: ST7789V
    bus_mode: single
    dimensions:
      height: ${LCD_HEIGHT}
      width: ${LCD_WIDTH}
      offset_width: 0
      offset_height: ${LCD_HEIGHT_OFFSET}
    buffer_size: 100%
    data_rate: ${LCD_SPI_DATA_RATE}
    rotation: ${LCD_ROTATION}
    spi_mode: MODE3
    invert_colors: true
    dc_pin: ${LCD_DC_PIN}
    reset_pin: ${LCD_RESET_PIN}
    update_interval: never
    auto_clear_enabled: false

lvgl:
  id: my_lvgl
  buffer_size: 100%
  disp_bg_color: 0x000000
  displays:
    - lcd_display
  pages:
    - id: main_page
      bg_color: 0x000000
      widgets:
        - label:
            text: "Hello World"
            align: CENTER
            text_color: 0xFFFFFF

What it's doing​

  • substitutions — pin assignments for Kamoji's ST7789 display, plus the device name. Change these first if you're wiring up different hardware.
  • esp32 / psram — Kamoji's board (ESP32-S3, 16MB flash, octal PSRAM) and the SDK options that enable it. See Performance design for why PSRAM matters here.
  • spi / display — sets up the SPI bus and the mipi_spi driver for the ST7789 panel, matching the wiring described in Components & Datasheets.
  • lvgl — Kamoji's production firmware builds its UI with LVGL too; this is the smallest possible LVGL page, a single centered label.
  • light / output — the backlight is its own dimmable light entity, turned on to full brightness in on_boot — without this the screen stays dark even once it's drawing content.

Build and flash it​

esphome run kamojihelloworld.yaml

This compiles the firmware, flashes it over USB, and opens a live log — pick your Kamoji's serial port when prompted. Once it boots, the display should light up with "Hello World" centered on a black background.

Where to go from here​

This config only drives the display — none of Kamoji's other sensors (gyroscope, microphone, touch, Wi-Fi) are configured. From here:

  • Browse the custom components used by the production firmware for building blocks (motion sensing, sound, touch, OTA) to add to your own config.
  • See Repurposing the hardware for two examples that go further and replace ESPHome entirely.