touchy-dankbot
An eavesdropping desk robot: it listens to nearby conversation and asks a small LLM for a witty one-liner, then shows it on a touchy-pad display — a one-line marquee scrolling across an addressable-LED matrix, or a wrapped text field on an LCD.
dankbot is a local (not connected to the internet) art experiment — a pendant LED
pillar that overhears, quips, and scrolls. It runs on a Raspberry-Pi-class box,
with a USB mic for ears and a touchy-pad display (an LED matrix, or any
touchy-pad LCD) for a mouth, and it uses an Ollama instance for the wit.
Status: early. Today this is the responder + listener: text (or speech) in, quip out — served by a remote Ollama server (no local model), optionally shown on a touchy-pad. Speech-to-text runs locally with Moonshine Voice.
How it works
[ people talking nearby ]
|
v
[ mic + VAD + STT ] Moonshine Voice — on-device, CPU-only
| text, one utterance at a time
v
[ utterance gate ] >= a few content words, de-duplicated
|
v
[ dankbot responder ] a witty line via a remote Ollama LLM
| a one-to-two-sentence quip, or /notfunny
v
[ touchy-pad display ] scrolling marquee (LED) / wrapped text (LCD)
Two halves, usable independently:
- Audio in (
dankbot listen) — mic -> transcript -> gate -> LLM, loggingHEARD:/SKIP(...)/REPLY:per utterance. - LED out (
dankbot listen) — each quip is a single property write on a touchy-pad; an LED matrix scrolls it, a tall LCD wraps it in a text field. No screen re-upload.
Install
Requires Python 3.11-3.14.
pip install touchy-dankbot # or: pipx install touchy-dankbot
That pulls the touchy-pad host library
(>= 0.4.0) from PyPI for the pad output. The LLM / STT half needs no
touchy-pad at all — with no pad attached the display is simply a logged warning.
The display relies on a recent touchy-pad host API
(SetPropertiesCmd / build_property_override + inline-recolour labels,
scroll_speed_px_s for the marquee speed, and the text_font override that
steps a long quip down a font size — that last one needs stage lb26, shipped
in 0.4.0); if the published version is too old, run
just use-touchy-local, which clones the git main (see Dev).
Without it the quip still shows, just at full size.
You also need a reachable Ollama server — a local ollama serve, or a
remote box over Tailscale / LAN. Point --url / DANKBOT_URL at it. On first
use, Moonshine downloads its STT model into ~/.cache/moonshine_voice and runs
offline afterwards.
For the mic you want a real USB array (the Seeed reSpeaker XVF3800 is what this
was built against — see docs/hardware.md); it is auto-selected
by name, so --device is only needed for a different input.
Quickstart
# One line:
dankbot reply --line "the bread is done baking"
# A file of overheard lines (one per line):
dankbot reply -f sim-overheard.txt
# What's pulled on the server?
dankbot models
# Listen to the mic (transcribe + witty reply, logged and scrolled on the pad):
dankbot listen
# Replay a file instead — no mic, no model (the pad still gets the quips):
dankbot listen --fake sim-overheard.txt
# Bake off models: packaged corpus × model matrix → jokemark.md + jokemark.json
dankbot jokemark
# Replay a saved bake-off: no server, no model — log + pad, 1 s per quip
dankbot jokemark --playback jokemark.json
Commands
| Command | What it does |
|---|---|
dankbot reply |
Read overheard lines (--line / -f FILE / stdin) and print a witty reply for each (--json for {input, reply, skip, model, raw} per line). Commands are stripped from the printed text, so a /notfunny reply prints nothing. |
dankbot models |
List the models the server has pulled. |
dankbot jokemark |
Bake off the quip stage: every model/params in a TOML matrix against the packaged overheard corpus (fetching missing models), writing a Markdown report and a JSON sidecar (default jokemark.md + jokemark.json). --dry-run shows the matrix without touching the network. If a touchy-pad is attached, each reply is also drawn on it as it is produced (entirely optional). --playback FILE replays a saved JSON report instead — no server, no model: entries are logged, quips shown on an attached pad, one second each. |
dankbot listen |
Listen to the mic, transcribe with Moonshine, log HEARD: / SKIP(...) / REPLY: per utterance, and scroll each quip on an attached touchy-pad; --fake FILE replays a text file instead (no mic, no model). |
Configuration is flag -> env -> default — click implements the precedence:
| Setting | Flag | Env | Default |
|---|---|---|---|
| Server URL | --url |
DANKBOT_URL |
https://kai.pygmy-map.ts.net |
| Model | --model |
DANKBOT_MODEL |
Rocinante-X-12B (Q4_K_M) |
| Persona | --persona / --persona-file |
DANKBOT_PERSONA |
the toaster robot |
| Temperature | --temperature |
DANKBOT_TEMP |
0.9 |
| min-p | --min-p |
DANKBOT_MIN_P |
0.05 |
| Context | --ctx |
DANKBOT_CTX |
4096 |
| Max output tokens | --max-tokens |
DANKBOT_MAX_TOKENS |
120 |
Native /api/chat |
--native |
DANKBOT_NATIVE |
off (use /v1) |
The default is what won the bake-off. Fallbacks, both already in the matrix:
--model hf.co/NousResearch/Hermes-3-Llama-3.1-8B-GGUF:latest (the disciplined
8B) or --model hf.co/bartowski/Human-Like-Mistral-Nemo-Instruct-2407-GGUF:Q8_0
(the 12B runner-up).
Every command also accepts --debug (env DANKBOT_DEBUG): it lowers the
Python logging level from WARNING to DEBUG, so the verbose detail — HTTP
request/retry lines, display rendering, cleanup failures — is printed on stderr
alongside the usual HEARD: / SKIP(...) / REPLY: lines.
Model bake-off (jokemark)
dankbot jokemark runs the quip stage over a corpus instead of one line at a
time:
just jokemark # or: dankbot jokemark
dankbot jokemark --dry-run # print the resolved matrix + line count
dankbot jokemark --models mine.toml -o report.md --no-pull
dankbot jokemark --playback jokemark.json # replay a saved run (no server)
- Corpus:
src/dankbot/assets/overheard.txt— the sixsim-overheard.txtsmoke lines plus restaurant/dinner-party conversation, shipped in the package and read withimportlib.resources. - Matrix:
src/dankbot/assets/jokemark-models.toml— model paths plus optionallabel,temperature,min_p,ctx,max_tokens,nativeandtimeout. TOML, so the file can carry comments about each experiment.[defaults]applies to every row; a row overrides it. Add a candidate model there (or in your own--modelsfile) to put it in the bake-off; comment an entry out to retire it, leaving the verdict beside it. - Fetching: missing models are pulled via Ollama's
/api/pullfirst (--no-pullrecords them as errors instead). - Pad (optional): if a touchy-pad is attached when the run starts, every
reply is also drawn on it as it arrives — the same parsed colour runs
dankbot listenscrolls. A missing pad is ignored (one warning, no per-reply probing), so the bake-off never waits for hardware;--display-modepicks the layout. - Reports: one Markdown file with a summary table (replies / skips / errors /
median / slowest) and, per model, every line with the quip it produced, the
raw output (commands visible) and the latency — plus a JSON sidecar
(
<out>.json,jokemark.jsonby default) with the same data, untruncated and including the colour runs. Both are generated artifacts. - Playback:
--playback jokemark.jsonreplays that sidecar without a server or a model — every entry is logged (label · overheard → REPLY: …, in the quip's display colours) and each non-skip quip is drawn on an attached touchy-pad, pausing one second so it can be read.
The first six corpus lines are the old manual-testing file, so the bake-off
keeps covering everything dankbot reply -f sim-overheard.txt used to.
The name of the game
A small model asked to "tell me a joke" regurgitates memorised dad jokes. Wit
comes from a persona baked into the system prompt plus a loosened
sampler (temperature=0.9, min_p=0.05). The persona also defines a tiny
command channel: a recognised command in the model's output is a directive
dankbot consumes — and never displays (an unknown slash token is recovered as
text).
/notfunny— "nothing worth saying": the reply is suppressed rather than showing a weak joke./color/NAME— colour the text —red/green/blue/yellow/white/purple/pink, or a0xRRGGBBhex, e.g./color/red Danger ahead.
Markdown emphasis becomes colour too, since the panel has no bold or italic:
*whirr*, *crickets*, *glitches and sparkles* scroll as the phrase alone,
cycling red → purple → blue → green → pink (an explicit /color still wins, and
any leftover * is dropped).
All of that lives in src/dankbot/persona.py and
src/dankbot/commands.py.
Listening (dankbot listen)
The audio-in half: open the mic, transcribe speech with Moonshine Voice
(streaming, CPU-only — the Raspberry Pi target), keep only utterances with at
least a few content words, and ask the LLM for a quip, logging HEARD: /
SKIP(...) / REPLY: lines and showing the quip on an attached touchy-pad
(that is always on; a missing pad just logs a warning).
Those log lines go to stderr and are rendered with
rich: HEARD: / SKIP(...) / REPLY: each get
their own colour, and the REPLY: line prints the quip in the same colours the
display scrolls for it (see src/dankbot/logs.py) — so
a colour reply is visible without the pad. A pipe or NO_COLOR falls back to
plain text, and the message text itself is unchanged.
| Setting | Flag | Env | Default |
|---|---|---|---|
| Capture device | --device |
DANKBOT_MIC |
auto (name ~ respeaker) |
| STT model size | --model-arch |
DANKBOT_MODEL_ARCH |
small (tiny/base/small/medium) |
| Min content words | --min-words |
DANKBOT_MIN_WORDS |
3 |
| Min duration (s) | --min-duration |
DANKBOT_MIN_DURATION |
0.6 |
| Repeat debounce (s) | --debounce |
DANKBOT_DEBOUNCE |
5.0 |
| Replay instead of the mic | --fake FILE |
— | off |
| JSON events | --json |
— | off |
| On-device screen name | --screen-name |
— | dankbot |
| Panel layout | --display-mode |
DANKBOT_DISPLAY_MODE |
auto (height rule) |
| Blank after quiet (s) | --clear-after |
DANKBOT_CLEAR_AFTER |
120 (0 = never) |
All the LLM flags (--url / --model / --persona / ...) are shared with
reply.
The display (on the touchy-pad)
The display half: dankbot builds one label screen on a touchy-pad, then each quip is a single property write (no screen re-upload). The layout comes from the panel's reported height:
<= 32px tall (an LED matrix) — one full-panel scrolling marquee (LONG_MODE_SCROLL_CIRCULAR). See docs/plans/ledout.md.- taller (an LCD) — one multiline text field that wraps to the panel width
and puts
...on the last visible line if a quip is too long (LONG_MODE_DOTS). A typical <100-character quip fits with room to spare. See docs/plans/lcdout.md.
--display-mode (DANKBOT_DISPLAY_MODE) overrides the rule with scroll or
multiline; the default auto uses the height. /color/NAME runs (and the
colour runs the parser makes from *emphasis*) are rendered in colour via LVGL
inline recolour on both layouts — e.g. /color/red Danger ahead shows
"Danger ahead" in red.
- The panel shows "I'm dankbot" on connect, then the quips; after
--clear-afterseconds with nothing new it goes blank. - On an LED matrix the marquee scrolls at 30 px/s —
DEFAULT_SCROLL_SPEED_PX_S(slower than LVGL's own 40 px/s default) — via touchy-pad'sscroll_speed_px_slabel field (stage LB19, touchy-pad 0.3.8). - The pad is opened lazily — plug it in at any time and the next quip lands on it. Nothing is fatal: no pad / an unplugged pad / an incompatible firmware all just log a warning and retry. Swapping an LED matrix for an LCD (or back) rebuilds the screen in the other layout on the next quip.
- Geometry and the base font come from the board's reported display size, so the same code drives an 8x8 / 32x8 LED matrix and a 480x272 LCD; 8/16/30 px are the compiled fonts, and the LCD picks the largest that leaves two lines.
- A long quip steps down to a smaller font instead of being cut off: the
label's drawn length (colour markup excluded) is fitted to the field, and the
text_fontpixel size rides in the same property batch as the text — ~170 characters fit at 30 px on the LCD, 500+ at 16 px. The marquee never needs this (it scrolls forever). See docs/plans/quipfit.md. - A fresh LED board is headless (
0x0) until its panel chain is provisioned:touchy pref from-template led-32x8. dankbot says so if it sees0x0. - The screen is saved as
F:host/s/dankbot.pb(--screen-nameto change it) — deliberately notdefault, sotouchy initcan't clobber it. - A quip is capped by the firmware's
SetPropertyCmdstring buffer — a 512-byte nanopb field, i.e. 511 characters (the terminator is counted); dankbot truncates a longer reply to fit, so a chatty model can't overflow it. Use--max-tokensto keep replies short if you prefer.
Dev
just install # venv + deps
just test # pytest (network-free)
DANKBOT_LIVE=1 just test # + one real request to the server / the mic
just lint # ruff format + check
just build # wheel + sdist into dist/
just bump-version # bump version, commit, tag, push (tag → PyPI publish)
The devcontainer (.devcontainer/) ships Python, Poetry, just, libusb (for the
touchy-pad USB transport) and ALSA / PortAudio (for the mic) — open it in VS Code
and just test works. By default the touchy-pad dependency is the published
PyPI package; just use-touchy-local clones (or fast-forwards)
upstream into the git-ignored
reference/touchy-pad and depends on that checkout's app/ host library while
hacking on touchy-pad itself (just use-touchy-pypi puts the published package
back).
Only src/dankbot/display.py imports touchy_pad,
and it does so lazily, so the rest of dankbot (and the whole test suite) runs
with no touchy-pad and no hardware.
Contributing
you probably don't want this yet.
I'm okay with using AI tools to help make code — I used them a fair amount on this project (one of my first experiments with not writing all my code "by hand"). But some of my other open-source projects have shown me the current hell that PR management is becoming, so I'd love any contributions (and I promise to be kind), with two asks:
- Send only PRs you are willing to sign off as "nicely written" (with your own experience as a software engineer). If your little AI buddy made something a bit ugly, iterate with it until it isn't.
- Keep PRs fairly atomic — touch just the code a single, nicely defined feature or bug-fix needs.
- Only send tested code you've run against real hardware (not just the simulator).
License
GPL-3.0-or-later — see LICENSE. Copyright 2026 S. Kevin Hester, kevinh@geeksville.com.
Metadata
Release files for touchy-dankbot 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| touchy_dankbot-0.1.1.tar.gz | 69.1 kB | With provenance | Details for touchy_dankbot-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| touchy_dankbot-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for touchy_dankbot-0.1.1-py3-none-any.whl |
Total release size: 139.6 kB
Release files / touchy_dankbot-0.1.1.tar.gz
| Download URL | touchy_dankbot-0.1.1.tar.gz |
|---|---|
| Size | 69.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9150b5bf44afee8c97418b42effb1cf2687e79b4e44e3b21c6036f97a7085952
|
|
BLAKE2b-256 checksum How to use checksums |
0be4b1035d66f71bd02d6b269bf3df7d1c9f0d1e6815acd029c6221bccc91956
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logRelease files / touchy_dankbot-0.1.1-py3-none-any.whl
| Download URL | touchy_dankbot-0.1.1-py3-none-any.whl |
|---|---|
| Size | 70.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f73a21184346c901b14fe3fcbf603b07db5e7ee1baa14337be789ec4a6a8f085
|
|
BLAKE2b-256 checksum How to use checksums |
81adc49c80ef0ea378fe8bd387d686c754bcaf4a0dc74c315621e99786d7c0f8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logSecurity for touchy-dankbot 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for touchy_dankbot-0.1.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.