ED1 Citilab Board - Home Assistant Integration

ESPHome configuration for integrating the ED1 Citilab ESP32 educational board with Home Assistant.

Full documentation at docs.glifo.cat — hardware reference, ESPHome configuration guide, Home Assistant dashboards & automations, SmartIR integration, and more.

• 1.44" TFT Display (ST7735) — device status, IP, temperature
• 6 Capacitive Touch Buttons — binary sensors in Home Assistant
• Light Sensor — ambient light percentage
• Buzzer — PWM audio output + RTTTL melodies
• IR Receiver (38kHz) — remote control & SmartIR bridge
• LED Matrix (WS2812) — addressable RGB light via GPIO12
• Stepper Motors (2x 28BYJ-48) — via MCP23009 I/O expander
• Bluetooth Proxy — extends Home Assistant BLE range
• WiFi Signal, CPU Temperature, Uptime sensors

Supports both Rev 1.0 and Rev 2.3 boards. See the hardware reference for revision differences.

1. Clone and configure:

   git clone https://github.com/glifocat/ed1-hoas.git
   cp secrets.sample.yaml secrets.yaml
   # Edit secrets.yaml with your WiFi and API credentials

2. Choose a sample configuration and copy it along with secrets.yaml, fonts/, and packages/ to your ESPHome config directory.

3. Flash via ESPHome add-on — the device auto-discovers in Home Assistant.

Full setup guide →

ed1-gambita.yaml is a personal experiment kept here as a worked example, not a config to copy. It drives the display from an external MQTT status topic, showing a voice assistant's state as one of eight animated faces — but it is hardwired to one private setup (a specific broker, the NanoClaw v1 topic layout, Spanish labels), so anywhere else it just shows "unknown".

Two parts of it are reusable, both under include/:

• ed1_gambita_state.h — state parsing and a watchdog with no ESPHome dependency, so it compiles and is unit-tested on a normal machine.
• ed1_gambita_faces.h — the drawing, templated on the display type.

tests/render_faces.cpp rasterises that real drawing code into an image on your laptop, which makes display work reviewable with no board attached.

The scene deck turns the ED1 into a physical Home Assistant remote — no automations to write, no entity IDs to copy:

1. Flash ed1-scene-deck.sample.yaml

2. Import the companion blueprint:

   

3. Create an automation from it and pick an action per button (real pickers — scenes, scripts, or any action sequence)

4. Edit the button labels on the deck's device page in HA — type the text and press Enter to commit (the field sends nothing until you do); the display updates live

You don't need to clone this repo — ESPHome can pull the packages straight from GitHub. Credentials are injected via substitutions, because remote packages can't read your secrets.yaml directly:

substitutions:
  device_name: ed1-livingroom
  friendly_name: ED1 Living Room
  ap_ssid: ED1-LivingRoom-Rescue
  # Credentials injected into the packages
  wifi_ssid: !secret wifi_ssid
  wifi_password: !secret wifi_password
  fallback_ap_password: !secret fallback_ap_password
  api_encryption_key: !secret api_encryption_key
  ota_password: !secret ota_password
  # Fonts resolve against YOUR config dir, so point pixelmix at this repo
  pixelmix_font: "https://raw.githubusercontent.com/glifocat/ed1-hoas/main/fonts/pixelmix/pixelmix.ttf"

packages:
  ed1:
    url: https://github.com/glifocat/ed1-hoas
    ref: v1.0.1  # pin a release tag (or use main to track latest)
    refresh: 1d
    files:
      - packages/display-colors.yaml
      - packages/display-layout.yaml
      - packages/core.yaml
      - packages/hardware.yaml
      - packages/display.yaml
      - packages/fonts.yaml
      - packages/buzzer.yaml
      - packages/buttons.yaml
      - packages/sensors.yaml

Notes:

• Pin ref: to a release tag for reproducible builds. Releases follow SemVer — substitution or component ID renames only happen in major versions.
• Package dependencies: buttons.yaml needs buzzer.yaml (button sounds), and display.yaml needs hardware.yaml, fonts.yaml, display-colors.yaml and display-layout.yaml. The list above is a working baseline.
• MQTT: add packages/mqtt.yaml to the list and provide mqtt_broker, mqtt_user and mqtt_password substitutions.

• Home Assistant with ESPHome Add-on
• ED1 Citilab Board (Rev 1.0 or Rev 2.3)
• USB-C cable + CP210x USB Driver

ed1-hoas/
├── ed1-*.yaml                     # Sample configurations
├── secrets.sample.yaml            # Credentials template
├── packages/                      # Modular ESPHome components
│   ├── core.yaml                  # ESP32, logger, API, OTA, WiFi
│   ├── hardware.yaml              # SPI and I2C buses
│   ├── display.yaml               # TFT ST7735 display
│   ├── display-colors.yaml        # Color palette definitions
│   ├── display-layout.yaml        # Screen layout constants
│   ├── display-settings.yaml      # Runtime display theme settings
│   ├── fonts.yaml                 # Fonts + Material Symbols icons
│   ├── buzzer.yaml                # PWM output + RTTTL melodies
│   ├── buttons.yaml               # 6 capacitive touch buttons
│   ├── sensors.yaml               # WiFi, uptime, temp, light sensors
│   ├── bluetooth.yaml             # BLE tracker + proxy
│   ├── ir-receiver.yaml           # 38kHz IR receiver
│   ├── ir-transmitter.yaml        # IR transmitter (Rev 1.0, experimental)
│   ├── led-matrix.yaml            # 32x8 WS2812B LED matrix
│   ├── mqtt.yaml                  # MQTT broker connectivity (optional)
│   └── stepper.yaml               # 28BYJ-48 stepper motors via MCP23009
├── fonts/                         # Pixelmix font
├── scripts/                       # Utility scripts
├── docs/                          # Hardware reference files
│   ├── images/                    # Board photos (CC BY-SA 4.0)
│   └── datasheets/                # Component PDFs
├── CONTRIBUTING.md
├── LICENSE
└── NOTICE

Want to contribute? Read the contributing guidelines to get started.

• Created and maintained by — glifocat
• Original hardware documentation and advice — vcasado
• ED1 Board — Citilab Edutec
• ESPHome — esphome.io

• Mintlify — free Pro plan through the Mintlify OSS Program
• Kilo Code — enterprise access through the Kilo OSS Program

• Board images — Citilab Market (CC BY-SA 4.0)
• Pixelmix font — Andrew Tyler (CC BY-NC-ND 3.0)

This project is licensed under the Apache License 2.0. See NOTICE for details.

• Full Documentation
• ESPHome Documentation
• Home Assistant
• Citilab