Baike.dev
All toolsOnline toolsAI codingTrendingOpen sourceNewsSubmit
Log in
< Back to tools
G

geekmagic-hacs

> 编程语言
Open source

Home Assistant integration for GeekMagic displays (SmallTV Pro/Ultra). Server-side rendering, no device flashing required.

395 stars0 likes1 views
WebsiteGitHub

About

Home Assistant integration for GeekMagic displays (SmallTV Pro/Ultra). Server-side rendering, no device flashing required.

GeekMagic Display for Home Assistant

A Home Assistant custom integration for GeekMagic displays (SmallTV Pro, Ultra, and similar ESP8266/ESP32-based devices).

How it works: This integration renders dashboard images directly in Home Assistant using Python/Pillow and pushes them to your GeekMagic device over HTTP. It supports the known stock firmware profiles and the newer SD_PRO-style firmware used by some Ultra units.


Disclaimers

Early Software: This project is in active development. Expect bugs, breaking changes, and incomplete features. The API and configuration format may change between versions.

Vibe Coded: This integration was largely vibe-coded with AI assistance. While functional, it may contain unconventional patterns or rough edges. Contributions and feedback welcome!


Background & Credits

I have a GeekMagic Ultra with ESP8266, which has limited possibilities for flashing with ESPHome. Instead of fighting the hardware, this integration takes a different approach: render everything server-side and push images to the device.

Special thanks to:

  • The Home Assistant Community thread for documenting GeekMagic device capabilities
  • Aydar (@aydarik) for sharing the bash script that demonstrated how to push images to these devices - the core inspiration for this integration

Dashboard Samples

The same dashboards in the StandBy theme (widgets on translucent cards) and the Night theme (a single red ramp for the bedside, overriding every widget colour):

Binary Sensor States & Icons

Binary sensors display human-readable states and state-specific icons based on their device_class. Icons are sourced from Home Assistant's official icon definitions.

Domain State Icons

Entities like lights, switches, and fans show different icons based on their state (on/off).

Widget Gallery

Widget 1x1 1x2 2x1 2x2 2x3 3x3
Gauge (Bar)
Gauge (Ring)
Gauge (Arc)
Entity (Icon)
Entity (Plain)
Clock
Text
Progress
Weather
Status
Chart
Candlestick
Climate
Attribute List

Candlestick Chart

Display OHLC (Open/High/Low/Close) candlestick charts from any numeric entity's history. Configurable candle intervals (1 hour, 4 hours, 1 day) and count.

Rendering Engine

All rendering is powered by the Blitz HTML/CSS engine via blitz-py (Stylo + Taffy + Parley + Vello — no browser). Every widget is an HTML fragment rasterized per-cell, so real CSS drives the design: flexbox, gradients, glows, border-radius, media queries, SVG charts, embedded fonts. Each cell is its own CSS viewport — one widget template adapts fluidly from a 76px 3×3 cell to 240px fullscreen, shedding detail bands as space runs out. Themes are full stylesheets (fonts, chrome, backdrops, overlay effects like CRT scanlines), not just palettes.

blitz-py ships prebuilt wheels on PyPI (Linux glibc/musl x86_64 + aarch64, macOS, Windows) and installs automatically with the integration.

HTML Widget

Design your own cells with HTML/CSS + Jinja. A 240×240 cell renders in ~20-40ms.

Modern CSS works: gradients (linear/radial/conic), border-radius, box-shadow glows, translucent rgba() fills and borders, flexbox, CSS grid, media queries, and viewport units.

Fluid templates

Each cell is its own CSS viewport, so one template adapts to every cell size — vmin/vw scale the type with the cell, and media queries shed detail when space runs out. A built-in fluid kit is injected into every document:

Class Purpose
.cell Flex-column scaffold filling the cell (space-evenly); add .row for horizontal
.t-hero Primary value — scales with cell size, capped by width
.t-value Secondary emphasized value
.t-unit Unit suffix, secondary color
.t-label Caps caption, tertiary color
.hide-short Hidden when the cell is under 100px tall
.hide-narrow Hidden when the cell is under 100px wide
.hide-small Hidden when either dimension is under 130px

The same template at fullscreen, 2×2, and 3×3 — hero scales, captions and detail bands drop out automatically:

xml

  

  

Samples are generated by scripts/generate_html_samples.py.

The HTML option is a Jinja template with access to entity data:

xml

  

  
  • state, name, unit, attributes — the widget's configured entity
  • states('sensor.x'), state_attr('sensor.x', 'attr'), is_state('sensor.x', 'on') — any referenced entity is tracked and pre-fetched automatically
  • now — timezone-aware current datetime
  • Theme colors as CSS variables: var(--text-primary), var(--text-secondary), var(--text-tertiary), var(--primary), var(--success), var(--warning), var(--error), var(--info), var(--muted), var(--bg)

Limitations: no JavaScript, no network fetches (use data: URIs for images), no background-clip: text, no text-shadow.

Animated Widgets (opt-in)

Turn on the device's Animations switch entity and any HTML widget with its Animate option enabled renders its CSS animations (@keyframes, transitions) to a looping animated GIF which the display plays natively. Views without animated widgets keep the smaller/faster JPEG path, and static cells in an animated view are rendered once and shared across frames. The Animation Loop option sets the loop length (0.8–4s; the view uses the longest loop among its widgets, at 10fps up to 2s and 7fps beyond).

Favor ambient motion over movement — glows that breathe, gradients that drift, colors that shift. Opacity, background-color, text color, box-shadow, and background-position all interpolate:

xml

Seamless-loop rules: animation durations should equal (or evenly divide) the loop length, and drifting gradients must tile — use a 90° gradient whose first and last color stops match (diagonal gradients show a seam when the tile repeats).

Animations are off by default: a GIF costs upload size (~100KB vs ~30KB JPEG) and device decode time.

Layout Examples

Fullscreen & Grid Layouts

Split Layouts

Column & Row Layouts

Hero Layouts

Sidebar Layouts

Themes

Choose from 17 built-in themes that go beyond just colors — they apply a complete design system: typography (rounded Nunito font on most themes), spacing, shapes, tinted gauge tracks, and visual effects.

The default watchOS theme is inspired by Apple's watchOS Human Interface Guidelines: true-black background, Apple system colors (red/orange/yellow/green/mint/teal/cyan/blue/indigo/purple/pink), opacity-based text hierarchy, tinted Activity-ring style gauges, and no card chrome — widgets float on the background for maximum information density. StandBy is the same system on translucent cards, like iOS StandBy widgets; Night is a red-on-black bedside mode that overrides every widget colour.

Dark Themes

watchOS StandBy Night Classic Minimal Neon Retro Soft
Default — Apple watchOS HIG-inspired Subtle card chrome, system colors Sharp, monochrome Cyberpunk with glow Terminal scanlines Cozy, very rounded

Colored & Light Themes

Ocean Sunset Forest Light Candy
Deep blue, nautical Warm coral/orange Natural earth tones Clean white background Playful pastels

Statement Themes

Blueprint Ink Aurora Brutal
Engineering drawing on drafting-grid paper Warm newsprint with one pot of red ink Luminous mesh-gradient poster, frosted glass Neo-brutalism: hard borders, harder shadows

Features

  • 15 widget types: Clock, entity, attribute list, media, chart, candlestick, text, gauge, progress, weather, status, climate, camera, and more
  • 19 layout options: Fullscreen, grids, splits, hero variants, sidebars, and more
  • 15 visual themes: watchOS (default), Classic, Minimal, Neon, Retro, Soft, Light, Ocean, Sunset, Forest, Candy, Blueprint, Ink, Aurora, Brutal
  • Visual configuration: Custom sidebar panel with live preview
  • Global views: Create views once, assign to multiple devices
  • Multi-screen support: Assign multiple views per device with auto-cycling
  • Notification service: Show temporary alerts with text, icons, or camera images
  • Pure Python rendering: Uses Pillow for image generation (no browser required)
  • Configurable refresh: Updates every 5-300 seconds

Installation

HACS (Recommended)

  1. Open HACS in Home Assistant
  2. Click "Custom repositories"
  3. Add this repository URL
  4. Install "GeekMagic Display"
  5. Restart Home Assistant

Manual

  1. Copy custom_components/geekmagic to your Home Assistant's custom_components folder
  2. Restart Home Assistant

Configuration

Adding a Device

  1. Go to Settings → Devices & Services
  2. Click Add Integration
  3. Search for "GeekMagic"
  4. Enter your device's IP address

Using the GeekMagic Panel

After installation, a GeekMagic item appears in your sidebar.

Views Tab

Create and manage display views:

  • Create views with the "+ Add View" button
  • Edit views by clicking on them
  • Delete views via the menu on each card

View Editor

The editor provides a live preview and widget configuration:

  • Preview: See real-time rendering as you configure
  • Layout: Choose grid size (2x2, 2x3, 3x2, hero, split, etc.)
  • Theme: Select from 10 visual themes
  • Widgets: Each slot shows a position grid - click cells to swap widget positions
  • Entity picker: Native Home Assistant entity selector with filtering

Devices Tab

Assign views to your GeekMagic devices:

  • Check which views each device should display
  • Devices automatically cycle through assigned views
  • Drag to reorder the rotation sequence

Device Info Page

Each device exposes entities for brightness, refresh interval, mode selection, and status:


Entities

Each GeekMagic device creates the following entities for control and monitoring:

Controls

Entity Type Description
number.geekmagic_brightness Number Display brightness (0-100%)
number.geekmagic_refresh_interval Number Update interval (5-300 seconds)
number.geekmagic_cycle_interval Number View cycle interval (0 = manual only)
select.geekmagic_mode Select Device mode (Custom Views, Clock, Weather, System Info)
select.geekmagic_current_view Select Currently displayed view (when in Custom mode)
switch.geekmagic_active Switch Enable/disable the display (sleep/wake)
switch.geekmagic_view_cycling Switch Enable/disable automatic view cycling

Sensors

| Entity | Type | Description | |--------|

Issues· 59 open

View all issuesOpen on GitHub

No open issues yet, or sync has not completed.

> Tags

Pythoncustom-integrationdisplayesp8266geekmagic

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026
UpdatedSep 17, 2026
Category编程语言
PricingOpen source

> Related tools

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言