Glassworks Principles
An opinionated, simple Home Assistant panel controller. What Glassworks is, what it isn't, and the rules every part follows.
On this page
Glassworks turns a wall panel into a Home Assistant device. It is opinionated on purpose. This page
says what we build, what we don't, and the rules each part follows. When a feature, a PR or an issue
goes against it, point here. If the rule is wrong, change this page first, in a Decide: issue,
and the code after.
In one sentence
Home Assistant is the brain. The panel is a screen, mics, a speaker, sensors and radios on a wall, and Glassworks hands them to Home Assistant, simply.
Principles
- Home Assistant is the brain. Glassworks has no automations, rules, scenes, schedules or user accounts. If it decides something about the home, it belongs in HA.
- ESPHome is the wire. The panel is an ESPHome device. Its state, settings and commands go over the ESPHome API, and nothing else controls it.
- The dashboard is the UI. The panel shows a HA dashboard. We don't draw our own home screens. We only draw what the panel itself does: setup, voice, timers, notifications, calls.
- Nothing to install in HA. No custom integration, nothing from the marketplace, no cloud, no account with us. Adopting the ESPHome device is the whole setup.
- Open standards out. When the panel talks to something other than HA, it uses a standard that thing already speaks: Sendspin, Matter, ONVIF. Never a protocol only our code speaks.
- Local only. No cloud, no telemetry, no phoning home. It works with the internet down.
- Off by default, cheap when on. A feature you didn't turn on costs nothing. The slowest frame we support (today the S1: 32-bit, with its RAM shared with the web engine) sets the budget.
- Write it once. A feature is written for every device. What only one device has stays in that device's frame.
- Never brick, always a way back. Read first, write second. Back up, verify, and offer an undo for every change to a device.
- Simple beats complete. One feature done well beats ten settings. If a setting exists only because we couldn't decide, decide.
What we're not building
| Not this | Because | Use instead |
|---|---|---|
| A kiosk browser with hundreds of options | Every option is a setting someone has to understand | The HA dashboard, and the few settings a panel needs |
| A dashboard designer, or our own home UI | HA has dashboards | HA dashboards, and the marketplace's cards if you want them |
| An automation engine | HA has automations | HA automations, scripts and blueprints |
| A fleet manager that works around HA | Settings are entities, so HA can already set them on every panel | Scenes and scripts, or the Manage page, which goes through HA |
| A voice assistant | HA's Assist does the thinking | The panel is an Assist satellite |
| A media centre | Music Assistant exists | The panel is a Sendspin player |
| A security system or an NVR | That needs certification and storage we don't have | The panel can be a camera and a sensor for one |
| A cloud service | Principle 6 | Nothing |
| A HA custom integration | Principle 4 | ESPHome |
The parts
Core (dev.glassworks)
What runs on every panel: the ESPHome device, the screen policy (presence, light, idle, night), the web engine that shows the dashboard, setup, the Manage page, and the pane host.
- Device-neutral. No device paths, no vendor services. That's the frame's job.
- Small. Something goes into the core only when two panes need it, or every panel does. Until then it lives in the pane.
- Confined. Android versions are read only in
dev.glassworks.platform. GeckoView is used only indev.glassworks.engine.gecko. Tests enforce both. - Stable for panes. After v1, a change to the pane API needs a reason good enough to break every pane.
- MPL-2.0, file by file.
Frames (frames/<id>, e.g. aqara-s1-plus)
A description of one device: its sensors, its ABIs, how Kiln installs it, and the panes only it can have (the S1's wall base).
- A frame adds no features. If a feature would make sense on another device, it's a pane, and
the frame provides the hardware it needs (a
PresenceSource, a radio backend). - A frame hides its vendor. Vendor daemons, binder calls and serial ports stay behind the frame's interfaces.
- No vendor bytes in the repo. Describe offsets and symbols, never commit firmware.
Panes
A feature the panel can have or leave out. The rules are in What makes a pane. In short:
- It adds something only the panel can do. If a HA dashboard can do it, it's a dashboard.
- It works through ESPHome alone. State as entities, the settings worth changing from HA as
config entities, commands as ESPHome actions, reports as events. One approved exception
(2026-11-13, #118): a report whose name the automation chose, like a notification's button,
goes out as a bus event (
esphome.<name>), because HA's event entity only fires names it listed up front. It is still ESPHome alone and needs no option in HA. - Other protocols are opt-in outputs. An open standard something else already speaks, off by default, with the pane still working without it.
- The panel's sign-in only reads. The panel may read from HA what ESPHome can't carry (the dashboard, the Thread network, a camera stream), and never controls HA with it. A person signed in on the Manage page acts with their own HA rights, like the HA app does.
Also:
- Off by default unless the frame says otherwise. It declares what it
requires, and frames without that hardware don't show it at all (maintainer, 2026-11-15). - One pane, one feature. A pane owns its own entities and settings keys, and talks to other
panes only through
PanelEventand services inPaneContext.
Entities
The ESPHome device is an API, not the settings screen. People set panels up on the Manage page, and HA's device page stays short. So every entity has a place:
| Kind | Category | Enabled by default | Example |
|---|---|---|---|
| Something people put on a dashboard or automate on | none | Yes | Presence, screen on/off, the media player |
| A setting someone would change from HA, for one panel or the whole house | CONFIG |
Only the common ones | Night mode, wake word, do not disturb |
| Health and versions | DIAGNOSTIC |
No, except the few people check | Wi-Fi signal, CPU, radio firmware |
- A pane adds at most a handful of uncategorised entities. Everything else is config or diagnostic.
- Enabled by default only if people reach for it day to day. Restarting the app, yes. Changing the radio mode, no: that's set once, on the panel or the Manage page. Anyone can turn a disabled entity on from HA's device page.
- Not every setting is an entity. Hardware calibration, one-off setup and anything nobody would change from an automation stay on the panel and its Manage page.
- A pane that's off adds nothing to the list a person sees.
Libraries (libs/*)
Protocols, written so anyone can use them: esphome-api, esphome-api-android, improv,
bluetooth-proxy, sendspin, voice.
- One protocol per library, with no pane or core dependency: a library may use another library
(
voiceandsendspinuseesphome-api), never the Pane API, the core or an app. Someone building something else should be able to take it as it is.LibraryBoundaryTestchecks this. - Plain Kotlin where possible. JVM libraries have no Android imports, so a JVM test can drive them.
- Tested against the reference.
esphome-apiis checked againstaioesphomeapi, and Sendspin against a real server. If the reference disagrees, the reference wins. - MIT. Code ported from elsewhere keeps its own licence and ships it in the artifact:
voice'sMicroFrontend.ktis Apache-2.0 and BSD-3-Clause.
Kiln (kiln/)
The installer. A web page that installs Glassworks on a frame over USB, with nothing to install on your computer.
- RAM first. Boot from RAM (FEL,
fastboot boot) before writing anything. - Backup, hash, verify. Every partition we write is backed up and read back.
- Always an undo. The restore puts the device back as it was.
- One recipe per frame. The core of Kiln doesn't know about any one device.
Who does what
| Job | Home Assistant | The panel |
|---|---|---|
| Decide what happens | Automations, scripts, scenes | Nothing |
| Show the home | Dashboards | Shows the dashboard |
| Settings for every panel | Scenes and scripts, on config entities | Applies its own |
| Who may change what | HA users and permissions | Follows them |
| Voice | Assist (wake word in HA or on the panel, STT, intent, TTS) | Mics, speaker, wake word |
| Music | Music Assistant | A Sendspin player |
| Hardware: presence, light, radio, Bluetooth, camera, NFC | Uses it as entities | Provides it |
| Interrupt the user (ring, alert, wake the screen) | Says when, through an ESPHome action | Does it |
Before you add something
Ask, in this order. A "no" to any of them means it doesn't ship as it is.
- Can HA already do it? With an automation, a script, a dashboard or a card? Then document the recipe instead.
- Does it need something installed in HA? Then rethink it.
- Does it work over ESPHome alone, with no setup beyond adopting the device?
- If it speaks another protocol: is that an open standard, opt-in, and is the feature still whole without it?
- Is it off by default, and cheap on the slowest frame when it's on?
- Does it work on every frame that has the hardware, not only the one you're testing on?
- Is there a way back? For anything that writes to a device.
When the answer is unclear, open a Decide: issue rather than building it.