ESPHome external component for Samsung 2x20 serial VFD

Component (components/samsung_vfd), example device config, README and
CLAUDE.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

examples/samsung-vfd.yaml

@@ -0,0 +1,173 @@
+# Example ESPHome config for a Samsung 2x20 serial VFD display.
+#
+# Copy this file into your ESPHome config folder (and add the keys below to
+# your secrets.yaml), or use it as a reference for your own device config.
+#
+# Wiring (display is 5V TTL serial, 9600 8N1):
+#   display RX  <-  ESP32 GPIO17 (TX)
+#   display GND <-> ESP32 GND
+#   display 5V  <-  5V supply (the display needs more current than the ESP32 regulator can give)
+#
+# To drive the display from GPIO1 (TX0, the USB serial pin) instead, set
+# `tx_pin: GPIO1` below and `baud_rate: 0` under `logger:` so log output does
+# not end up on the display.
+
+esphome:
+  name: samsung-vfd
+  friendly_name: Samsung VFD
+  on_boot:
+    priority: -100
+    then:
+      - samsung_vfd.clear:
+          id: vfd
+      - samsung_vfd.print:
+          id: vfd
+          text: "Hello World!"
+          centered: true
+      - delay: 3s
+      # Bring back the last text Home Assistant set for the top line.
+      - samsung_vfd.print:
+          id: vfd
+          line: 0
+          text: !lambda "return id(vfd_line1).state;"
+
+external_components:
+  - source: github://REPO_OWNER/REPO_NAME@main
+    components: [samsung_vfd]
+    refresh: 1d
+  # While developing the component, use the checkout instead:
+  # - source:
+  #     type: local
+  #     path: ../components
+
+esp32:
+  board: esp32dev
+  framework:
+    type: arduino
+
+logger:
+  level: INFO
+
+api:
+  encryption:
+    key: !secret api_key
+
+ota:
+  - platform: esphome
+    password: !secret ota_password
+
+wifi:
+  ssid: !secret wifi_ssid
+  password: !secret wifi_password
+  # Uncomment to pin a fixed address.
+  # manual_ip:
+  #   static_ip: 10.1.1.60
+  #   gateway: 10.1.1.1
+  #   subnet: 255.255.255.0
+  ap:
+    ssid: "Samsung VFD Fallback"
+    password: !secret fallback_password
+
+captive_portal:
+
+# SNTP so samsung_vfd.printf can show the local time.
+time:
+  - platform: sntp
+    id: sntp_time
+    timezone: Europe/Amsterdam
+    servers:
+      - 0.pool.ntp.org
+      - 1.pool.ntp.org
+
+uart:
+  id: uart_vfd
+  tx_pin: GPIO17
+  baud_rate: 9600
+  # The display is output-only for us; no rx_pin needed.
+
+samsung_vfd:
+  id: vfd
+  uart_id: uart_vfd
+  cols: 20
+  rows: 2
+  # Lines are padded to 20 chars and the display wraps by itself. Set to true
+  # only if line 2 ends up on the wrong row (sends CR LF between the lines).
+  send_newlines: false
+
+# Bottom line shows the SNTP clock every second, except while a status banner is up.
+interval:
+  - interval: 1s
+    then:
+      - if:
+          condition:
+            not:
+              script.is_running: show_status
+          then:
+            - samsung_vfd.printf:
+                id: vfd
+                time_id: sntp_time
+                line: 1
+                format: "%a %d %b  %H:%M:%S"
+
+# Full-screen centred banner for a while, then back to line 1 + clock.
+script:
+  - id: show_status
+    mode: restart
+    parameters:
+      msg: string
+    then:
+      - samsung_vfd.print:
+          id: vfd
+          text: !lambda "return msg;"
+          centered: true
+      - delay: 10s
+      - samsung_vfd.print:
+          id: vfd
+          line: 0
+          text: !lambda "return id(vfd_line1).state;"
+      - samsung_vfd.printf:
+          id: vfd
+          time_id: sntp_time
+          line: 1
+          format: "%a %d %b  %H:%M:%S"
+
+# Two Home Assistant text entities you can type into from HA.
+text:
+  - platform: template
+    id: vfd_line1
+    name: "VFD line 1"
+    icon: mdi:text-box-outline
+    mode: text
+    max_length: 20
+    optimistic: true
+    restore_value: true
+    initial_value: ""
+    on_value:
+      then:
+        - if:
+            condition:
+              not:
+                script.is_running: show_status
+            then:
+              - samsung_vfd.print:
+                  id: vfd
+                  line: 0
+                  text: !lambda "return x;"
+
+  - platform: template
+    id: vfd_status
+    name: "VFD status"
+    icon: mdi:information-outline
+    mode: text
+    max_length: 40
+    optimistic: true
+    initial_value: ""
+    on_value:
+      then:
+        - if:
+            condition:
+              lambda: "return !x.empty();"
+            then:
+              - script.execute:
+                  id: show_status
+                  msg: !lambda "return x;"

examples/secrets.yaml.example

@@ -0,0 +1,7 @@
+# Copy to secrets.yaml (next to your device yaml) and fill in.
+wifi_ssid: "your-ssid"
+wifi_password: "your-wifi-password"
+ota_password: "choose-an-ota-password"
+fallback_password: "choose-a-fallback-ap-password"
+# Generate with: python -c "import secrets,base64;print(base64.b64encode(secrets.token_bytes(32)).decode())"
+api_key: "base64-32-byte-key"