Dots on Paper

Give your assistant a tiny face and a place on your desk.

An MCP and Home Assistant bridge that turns real assistant replies into readable e-ink screens. Four switchable characters, a calm reply view, and a little personality when an answer arrives.

heidot, imagined on e-ink. The calendar is fictional; the bridge is real. Watch the MP4 · The “NOO” film · X launch package

Working locally: authenticated publishing, rendering, browser preview, and MCP forwarding. Still to connect: your actual dot account, HA installation, and physical display. Verification and limits

What you get

• A local bridge with persistent replies and separate publishing/image keys.

• Three MCP tools: set_dot_status, publish_dot_reply, and get_dot_state.

• A Home Assistant image entity, reply/status sensors, character picker, actions, and new-reply events.

• TRMNL BYOS endpoints, ESPHome/OpenEPaperLink examples, and custom PNG/BMP sizes.

• Artist, Curious, Bookish, and Cool — switch the face without losing the answer.

• A standalone demo and ready-to-edit campaign assets.

Your dot or HA assistant → authenticated bridge → PNG / BMP → e-ink display

The dot deliberately publishes its answer through a tool. The bridge does not automatically watch every ChatGPT reply. Display refresh is controlled by the device; the film's smooth animation is an illustrative concept.

Related MCP server: stackchan-mcp

Run the bridge

From this repository's root, with Python 3.11+ and Node.js 22+ installed:

python tools/setup.py

Then start it:

Open http://127.0.0.1:9035 and select data/credentials.json in the connection panel. Setup creates a local virtual environment, installs the package, and initializes private keys without replacing or displaying them. The first state is “Waiting for your dot.”

With the bridge running, check it using .\run.ps1 -Doctor on Windows or .venv/bin/python tools/doctor.py on macOS/Linux. Setup, LAN access, Docker, and troubleshooting

Connect your real dot

Install the portable plugin or connect its MCP tools to your client. A cloud ChatGPT dot needs a reachable connection — a supported Secure MCP Tunnel or authenticated HTTPS endpoint. A localhost bridge alone is not reachable from the cloud.

After connecting, tell your dot:

Use Dots on Paper for answers in this conversation. Set it to thinking when you start. Publish a short version of your actual answer when you finish.

The local tools are implemented; private account access and device delivery need verification after installation. Real-dot connection guide · REST/API inputs

heidot is the personal dot behind this project's idea. Dots on Paper is the bridge name; configure your own dot's display name when publishing.

Displays and Home Assistant

Copy custom_components/dots_on_paper into HA's /config/custom_components/, restart HA, and add Dots on Paper in Devices & services. Use a bridge address reachable from HA. HA setup · Profiles, authentication, and refresh behavior

TRMNL cloud private-plugin rendering follows a different schedule and is not connected by this release. HACS publication is also pending.

Try the animation

node demo/serve.mjs

Open http://127.0.0.1:9024/?example=calendar-chaos. Switch all four dots, try the “NOO” conversation, or write a multiline reply. The layout handles paragraphs and lists; the examples do not change its rules.

The campaign includes GIFs, MP4s, native screen stills, and four short posts. The wife-texting exchange is a cancelled scripted draft; no message is sent. The Instinct-inspired image is an independent concept with no Instinct connector. Product facts

Publish and contribute

The source is on GitHub. HACS registration and a tagged release remain separate steps. GitHub release guide

Contributing and checks · Security · MIT license · Asset provenance