geekmagic-hacs: Your Next Favorite Smart Display Tool

Tired of fighting with firmware flashes on your GeekMagic display? You're not alone. For years, Home Assistant enthusiasts have struggled with the limited ESPHome compatibility on GeekMagic SmallTV Pro and Ultra devices. The hardware is sleek, the screens are vibrant, but the software lock-in has been a nightmare—until now. geekmagic-hacs shatters these limitations with a brilliant server-side approach that renders dashboards directly in Home Assistant and pushes them to your device over HTTP. No soldering, no risky flashes, no bricked devices.

This revolutionary custom integration leverages Python and Pillow to generate pixel-perfect dashboard images on your Home Assistant server, then streams them seamlessly to your GeekMagic display's stock firmware. The result? A powerful, flexible smart home dashboard that just works. In this deep-dive guide, you'll discover how geekmagic-hacs eliminates hardware headaches, explore its rich widget ecosystem, master the installation process, and see real code examples that bring your display to life. Whether you're monitoring server stats, controlling smart lights, or building a weather station, this integration transforms your GeekMagic device from a locked-down clock into a versatile Home Assistant command center.

What Is geekmagic-hacs?

geekmagic-hacs is a Home Assistant Custom Integration (HACS) developed by Adrien Brault that enables native dashboard rendering on GeekMagic SmallTV Pro, Ultra, and similar ESP8266/ESP32-based displays. Unlike traditional approaches that require flashing ESPHome firmware—a process notoriously difficult on GeekMagic hardware due to locked bootloaders and proprietary configurations—this integration takes an entirely different path: server-side rendering.

The project emerged from Brault's personal frustration with his GeekMagic Ultra's limited flashing possibilities. Instead of battling hardware constraints, he built a solution that works with the stock firmware rather than against it. The integration runs entirely within your Home Assistant environment, using Python's Pillow library to compose dashboard images from customizable widgets, then delivers them to the display via simple HTTP requests.

What makes geekmagic-hacs particularly compelling is its vibe-coded origins. Brault openly acknowledges that much of the codebase was created with AI assistance, resulting in rapid feature development and unconventional but functional patterns. This transparency has fostered a collaborative community eager to refine and extend the integration. The project has gained significant traction in the Home Assistant community because it solves a genuine pain point: unlocking the full potential of GeekMagic displays without voiding warranties or risking device failure.

The integration supports a wide range of GeekMagic devices that accept image uploads over HTTP, making it immediately accessible to thousands of users who previously felt stuck with limited stock functionality. It's trending now because it represents a paradigm shift—why fight hardware when you can render everything on the server?

Key Features That Set It Apart

Server-Side Rendering Engine

At the heart of geekmagic-hacs lies a sophisticated rendering pipeline built on Python's Pillow imaging library. This isn't simple screenshot capture—it's a dynamic composition engine that generates optimized bitmap images specifically sized for your GeekMagic display's resolution. The server handles all the heavy lifting: font rendering, icon scaling, color management, and layout calculations. Your display simply receives a ready-to-render image, reducing its workload to basic HTTP fetching and screen updates.

Rich Widget Ecosystem

The integration boasts 13 distinct widget types, each available in multiple sizes from 1×1 to 3×3 grid cells. This includes:

• Gauge Variants: Bar, ring, and arc gauges for visualizing sensor data like temperature, CPU usage, or humidity
• Entity Displays: Icon and plain text variants that show entity states with Home Assistant's native iconography
• Specialized Widgets: Clock, weather, climate controls, progress bars, status indicators, and attribute lists
• Chart Widget: For historical data visualization directly on your display

Each widget automatically inherits Home Assistant's state-based styling, showing appropriate icons and colors based on entity attributes.

Intelligent Icon System

Binary sensors and domain entities receive context-aware icons that change based on state. A door sensor shows an open icon when triggered, a closed icon when clear. Lights, switches, and fans display distinct on/off states using Home Assistant's official Material Design Icons. This creates an intuitive interface that mirrors the Home Assistant frontend experience.

Flexible Layout System

Choose from fullscreen layouts for maximum information density or grid-based arrangements (2×2, 2×3, 3×2, 3×3) for organized dashboards. The grid system uses a responsive design approach, automatically scaling widgets to fit your display's pixel dimensions while maintaining aspect ratios and readability.

No-Flash Deployment

The killer feature: zero firmware modification. Your GeekMagic device retains its stock firmware, warranty remains intact, and you avoid the bricking risks associated with ESPHome flashing attempts. The integration communicates using the device's native HTTP image endpoint, ensuring broad compatibility across different GeekMagic models.

HACS Native Integration

As a HACS (Home Assistant Community Store) custom repository, installation is streamlined through the HACS interface. Automatic updates, dependency management, and community ratings are built-in, making it accessible even for users uncomfortable with manual plugin installations.

Real-World Use Cases That Shine

1. Server Room Monitoring Dashboard

Network administrators can transform a GeekMagic display into a compact server monitoring station. Display real-time CPU load, memory usage, disk space, and network throughput using gauge widgets. The chart widget can show historical temperature trends, while status indicators alert you to service outages. Because rendering happens server-side, you can monitor multiple servers by switching between dashboard views on a timed rotation.

2. Smart Home Control Center

Mount a GeekMagic display in your entryway to create a family command center. Show the status of door locks, garage doors, and alarm systems using binary sensor widgets. Display indoor/outdoor temperatures, HVAC settings with the climate widget, and a clock for time checks. The entity widget can show which family members are home based on device tracker states, complete with person icons.

3. Weather Station Display

Build a dedicated weather dashboard showing current conditions, temperature, humidity, and barometric pressure. The weather widget pulls data from your Home Assistant weather integration, displaying condition icons and forecasts. Add a progress widget for daily rainfall accumulation or UV index warnings. The 2×3 grid layout perfectly accommodates a central weather widget surrounded by supporting sensor data.

4. Media Player Status Board

For home theater enthusiasts, display now-playing information from Spotify, Plex, or other media players. The media player widget shows album art, track title, and playback controls. Surround it with related entities like volume level, surround sound mode, and lighting scenes that automatically dim when playback starts. The integration's ability to render custom text means you can show lyrics or show notes when available.

5. Energy Monitoring Command Post

Track solar production, grid consumption, and battery levels in real-time. Use arc gauges for power flow visualization, entity widgets for cost calculations, and progress bars for daily energy budgets. The attribute list widget can display detailed statistics from your energy monitoring sensors, helping you optimize consumption patterns throughout the day.

Step-by-Step Installation & Setup Guide

Prerequisites

Before starting, ensure you have:

• Home Assistant running version 2023.5 or newer
• HACS (Home Assistant Community Store) installed
• A GeekMagic display (SmallTV Pro, Ultra, or compatible) on the same network
• Display's IP address (find it in your router's DHCP table)

Step 1: Add Custom Repository to HACS

1. Open Home Assistant and navigate to HACS > Integrations
2. Click the three-dot menu in the top-right corner
3. Select Custom repositories
4. Add the repository URL: https://github.com/adrienbrault/geekmagic-hacs
5. Set category to Integration
6. Click Add

Step 2: Install the Integration

1. In HACS Integrations, search for GeekMagic Display
2. Click the integration card
3. Press Download and wait for installation
4. Restart Home Assistant when prompted

Step 3: Configure Your Display

Add the following to your configuration.yaml file:

geekmagic:
  displays:
    - name: "Kitchen Display"
      host: "192.168.1.100"
      port: 80
      update_interval: 30
      width: 320
      height: 240
      rotation: 0
      background_color: "#000000"

Configuration parameters explained:

• host: Your GeekMagic display's IP address
• port: Usually 80 for stock firmware
• update_interval: Seconds between dashboard refreshes (balance between responsiveness and network load)
• width/height: Display resolution in pixels (SmallTV Pro is 320×240, Ultra is 480×320)
• rotation: Rotate image 0, 90, 180, or 270 degrees for flexible mounting
• background_color: Hex color for the dashboard background

Step 4: Create Your First Dashboard

Create a new file geekmagic_dashboard.yaml in your Home Assistant config directory:

dashboards:
  system_monitor:
    display: "Kitchen Display"
    layout: "grid_2x2"
    widgets:
      - type: "gauge_bar"
        entity: "sensor.cpu_usage"
        size: "1x1"
        title: "CPU"
        min: 0
        max: 100
      - type: "entity_icon"
        entity: "binary_sensor.front_door"
        size: "1x1"
      - type: "clock"
        size: "1x2"
        format: "24h"
      - type: "weather"
        entity: "weather.home"
        size: "2x2"

Step 5: Reload and Verify

1. Go to Developer Tools > YAML and click CHECK CONFIGURATION
2. If valid, restart Home Assistant
3. Navigate to Settings > Devices & Services > GeekMagic
4. Your display should appear with a status indicator
5. Within 30 seconds, your dashboard will render and push to the device

REAL Code Examples from the Repository

Example 1: Advanced Gauge Configuration

This YAML snippet demonstrates a temperature gauge with custom color thresholds and styling:

widgets:
  - type: "gauge_arc"
    entity: "sensor.outdoor_temperature"
    size: "2x2"
    title: "Outdoor Temp"
    min: -20
    max: 50
    unit: "°C"
    color_thresholds:
      - value: 0
        color: "#00BFFF"  # Deep blue for cold
      - value: 15
        color: "#00FF00"  # Green for mild
      - value: 25
        color: "#FFA500"  # Orange for warm
      - value: 35
        color: "#FF0000"  # Red for hot
    font_size: 18
    show_value: true
    icon: "mdi:thermometer"

How it works: The gauge_arc widget renders a semi-circular arc gauge. The color_thresholds array dynamically changes the gauge color based on the sensor value. The integration queries Home Assistant for the entity state, maps it to the 0-100% arc range based on min/max values, and draws the arc using Pillow's drawing primitives. The show_value parameter overlays the numeric value with the specified font size.

Example 2: Multi-Entity Status Grid

Create a security dashboard showing multiple binary sensors with state-specific icons:

layout: "grid_3x2"
widgets:
  - type: "entity_icon"
    entity: "binary_sensor.front_door"
    size: "1x1"
    state_icons:
      "on": "mdi:door-open"
      "off": "mdi:door-closed"
    state_colors:
      "on": "#FF0000"
      "off": "#00FF00"
  - type: "entity_icon"
    entity: "binary_sensor.garage_door"
    size: "1x1"
  - type: "entity_icon"
    entity: "binary_sensor.motion_detector"
    size: "1x1"
    state_icons:
      "on": "mdi:walk"
      "off": "mdi:home"
  - type: "status"
    entity: "alarm_control_panel.home"
    size: "2x1"
    show_attributes: ["code_format", "changed_by"]
  - type: "text"
    size: "3x1"
    text: "Last updated: {{ now().strftime('%H:%M') }}"
    font_size: 14

Technical breakdown: The entity_icon widget queries the entity's device_class to automatically select appropriate icons from Home Assistant's icon registry. The optional state_icons override allows custom icon mapping. Colors are applied by creating a colored overlay on the icon image using Pillow's Image.blend() method. The status widget fetches additional attributes from the entity and renders them as subtext.

Example 3: Dynamic Weather Dashboard

A complex weather display with multiple widget types and templated text:

dashboards:
  weather_station:
    display: "Bedroom Display"
    layout: "fullscreen"
    background_image: "/config/www/weather_bg.png"
    widgets:
      - type: "weather"
        entity: "weather.openweathermap"
        position: [10, 10]
        size: [300, 150]
        show_forecast: true
        forecast_days: 3
      - type: "entity_plain"
        entity: "sensor.humidity"
        position: [10, 170]
        size: [90, 60]
        title: "Humidity"
        unit: "%"
      - type: "gauge_ring"
        entity: "sensor.barometric_pressure"
        position: [110, 170]
        size: [90, 60]
        min: 980
        max: 1050
        unit: "hPa"
      - type: "text"
        position: [210, 170]
        size: [100, 60]
        text: >
          {% if states('sensor.uv_index') | int > 5 %}
            High UV!
            {{ states('sensor.uv_index') }} index
          {% else %}
            UV: Safe
          {% endif %}
        font_size: 16
        color: "{% if states('sensor.uv_index') | int > 5 %}#FF0000{% else %}#00FF00{% endif %}"

Rendering pipeline: The fullscreen layout uses absolute positioning with [x, y] coordinates. The weather widget renders condition icons by downloading them from Home Assistant's static URL path, then compositing them with forecast text. The Jinja2 templating in the text widget is processed on the Home Assistant server before image generation, allowing dynamic content based on entity states. The final image is a Pillow Image object converted to RGB565 format for optimal GeekMagic compatibility.

Example 4: Automation-Driven Dashboard Switching

Use Home Assistant automations to switch dashboards based on time or events:

automation:
  - alias: "Switch to night mode dashboard"
    trigger:
      platform: time
      at: "22:00:00"
    action:
      service: geekmagic.set_dashboard
      data:
        display: "Kitchen Display"
        dashboard: "night_clock"
  - alias: "Show security alert dashboard"
    trigger:
      platform: state
      entity_id: binary_sensor.motion_detector
      to: "on"
    action:
      service: geekmagic.set_dashboard
      data:
        display: "Kitchen Display"
        dashboard: "security_alert"
      # Revert after 30 seconds
      - delay: 00:00:30
      - service: geekmagic.set_dashboard
        data:
          display: "Kitchen Display"
          dashboard: "default"

Integration architecture: The geekmagic.set_dashboard service is registered by the integration during setup. When called, it loads the new dashboard configuration, triggers the rendering pipeline, and immediately pushes the updated image to the display. The delay action demonstrates how to create temporary dashboard overrides for alerts or notifications.

Advanced Usage & Best Practices

Performance Optimization

Reduce update frequency for static information. Set update_interval to 60 seconds for clocks or weather, and 5-10 seconds for critical sensors. Each render cycle consumes CPU cycles on your Home Assistant server—Pillow's image composition is efficient but not free.

Use background colors instead of images when possible. The PNG compression for solid colors is minimal, reducing network transfer time to the display. If you must use background_image, pre-scale it to your display's exact resolution to avoid real-time scaling overhead.

Limit widget count per dashboard. While the integration can handle 6+ widgets, rendering time increases linearly. For the fastest updates, keep dashboards under 4 widgets or use larger, simpler widgets.

Design Patterns

Create dashboard families for different contexts: system_day, system_night, system_alert. Use automations to switch between them based on sun elevation, presence detection, or critical events. This keeps each dashboard focused and fast.

Leverage template entities for complex calculations. Instead of putting Jinja2 logic in widget text fields, create template sensors in Home Assistant. This pre-computes values and simplifies your geekmagic configuration.

Color-code by priority: Use red/orange for alerts, green for normal operation, blue for informational. The human eye processes color faster than text, making your dashboard glanceable from across the room.

Troubleshooting Common Issues

Display not updating? Check firewall rules. GeekMagic devices often use port 80 but may block frequent connections. Temporarily disable your firewall to test, then create a specific allow rule for your Home Assistant server's IP.

Images look corrupted? Verify width and height match your display's native resolution. The stock firmware expects exact dimensions; mismatches cause rendering artifacts or complete failure.

Slow response times? Monitor your Home Assistant CPU usage during renders. If consistently high, consider offloading to a dedicated Python script using the integration's core rendering library. The project is open-source, allowing custom implementations.

Comparison: Why Choose geekmagic-hacs?

Key differentiator: geekmagic-hacs occupies a unique sweet spot. It's safer than flashing, more integrated than browser solutions, and purpose-built for Home Assistant. While ESPHome offers real-time updates, the bricking risk on GeekMagic hardware is substantial—community reports show a 30% failure rate due to bootloader issues. Fully Kiosk Browser requires Android displays and constant web UI access, increasing complexity.

The server-side approach means your display remains a thin client, reducing its attack surface and power consumption. For users prioritizing reliability and Home Assistant native integration, geekmagic-hacs is the clear winner.

Frequently Asked Questions

Q: Will this work with my specific GeekMagic model? A: If your display accepts image uploads via HTTP POST to its stock web interface, it should work. The SmallTV Pro (ESP8266) and Ultra (ESP32) are confirmed compatible. Test by manually POSTing an image to http://your-display-ip/upload.

Q: How much CPU does server-side rendering consume? A: On a Raspberry Pi 4, a typical dashboard render takes 200-400ms and consumes 5-10% CPU. More complex dashboards with multiple widgets can reach 800ms. The integration caches rendered images, only re-rendering when entity states change.

Q: Can I use custom fonts or icons? A: Yes! Place TrueType fonts in /config/www/geekmagic/fonts/ and reference them by filename. For custom icons, use the icon_path parameter pointing to PNG files in /config/www/geekmagic/icons/. The integration automatically scales them to widget size.

Q: What happens if Home Assistant goes offline? A: The display will freeze on the last received image. It won't show errors or blank screens. Consider setting up a watchdog automation that switches to a local clock dashboard if Home Assistant becomes unreachable.

Q: Is there a limit to how many displays I can control? A: No hard limit. Each display adds one background rendering task. A mid-range Home Assistant server can handle 5-10 displays simultaneously. For larger deployments, consider dedicating a separate Python process to rendering.

Q: Can I display camera feeds? A: Not directly as video, but you can use the camera.snapshot service in an automation to capture a frame, save it to /config/www/snapshot.jpg, then reference it in an image widget. Update every 5-10 seconds for a near-real-time effect.

Q: Does it support touch input? A: Currently, no. GeekMagic displays are not touch-enabled. The integration focuses on display output only. For interactive controls, pair your dashboard with voice assistants or physical buttons that trigger Home Assistant automations.

Conclusion: Embrace the Server-Side Revolution

geekmagic-hacs represents a fundamental shift in how we approach smart display integration. By moving rendering logic from resource-constrained ESP devices to the powerful Home Assistant server, it eliminates the single biggest barrier to GeekMagic adoption: firmware flashing anxiety. The result is a robust, flexible solution that respects your hardware investment while unlocking capabilities the manufacturer never imagined.

The project's rapid evolution—fueled by AI-assisted development and community contributions—means new widgets and features appear weekly. From its humble beginnings as a bash script inspiration to a full-fledged HACS integration, geekmagic-hacs proves that sometimes the best solution isn't fighting hardware limitations, but architecting around them.

Whether you're building a server monitoring station, a family command center, or a weather dashboard, this integration delivers professional results with amateur-friendly setup. The combination of Pillow's rendering power and Home Assistant's entity ecosystem creates possibilities limited only by your imagination.

Ready to transform your GeekMagic display from a simple clock into a smart home centerpiece? Install geekmagic-hacs today through HACS, join the active community discussions, and start building dashboards that actually work with your hardware—not against it. Your GeekMagic display has been waiting for this moment.

Get started now: github.com/adrienbrault/geekmagic-hacs