Pulse Kiosk v1 — Complete Setup Guide

Raspberry Pi 5 + Pi 7" Touch Display 2

Pulse Display Assistant is a Raspberry Pi kiosk OS purpose-built for Home Assistant dashboards. Each device self-provisions a hardened Chromium display with watchdogs, schedule-aware backlighting, and MQTT telemetry/control. A live overlay surfaces internal timers, alarms, reminders, now-playing info, plus on-demand news, weather, and sports snapshots—with clickable notification badges that stay synced to the backend schedule service. An optional Wyoming voice stack adds wake-word control, STT/TTS, and multi-turn conversations, while the LLM layer can hot-swap between OpenAI, Google Gemini, Anthropic Claude, Groq, Mistral AI, and OpenRouter so follow-up questions and automations route through whichever provider and model you prefer, all without leaving the Pulse display.

What Pulse can do today

• Hardened Chromium kiosk with watchdogs, self-healing restarts, and MQTT “home/update/reboot” buttons targeted at photo-frame style Lovelace dashboards.
• Overlay timeline that keeps alarms, timers, reminders, calendar events, now-playing info, and badge-driven info cards in sync with the backend scheduler.
• Full alarm/timer/reminder scheduler (manual UI, MQTT, or voice shortcuts) plus remote completion/delay actions from the overlay itself.
• Local ICS/WebCal polling with RRULE expansion for recurring events, multi-VALARM support, “declined” attendee detection, on-screen calendar cards, and auto-suppressed pop-ups for meetings you said “No” to.
• Optional Wyoming voice stack (wake word, Whisper STT, Piper TTS) with shortcut intents for news/weather/sports and LLM routing between 6 providers: OpenAI, Gemini, Anthropic Claude, Groq, Mistral AI, and OpenRouter.
• MQTT telemetry, syslog streaming, and safe-reboot guardrails for remote monitoring, plus built-in OTA-style updates triggered from Home Assistant.
• Sunrise/sunset-aware backlight control, Bluetooth autoconnect for external speakers, and one-touch audio tests to confirm volume changes.
• Printable hardware accessories (mic stand, speaker cups, Pi 5 case) and ready-made scripts for kiosk recovery, calendar snapshots, and service restarts.

How to obtain, get help, and contribute

• Obtain: clone from GitHub (git clone https://github.com/weirdtangent/pulse-os.git) and follow the setup steps below (we publish interim commits, not just tagged drops).
• Bugs & enhancements: open issues with repro details and expected behavior.
• Contribute: follow CONTRIBUTING.md and TESTING.md for coding standards (Black 120 cols, Ruff) and required checks (ruff, black, pytest).
• Security reports: use the process in SECURITY.md; please do not open public issues for vulnerabilities.
• CPE: not published / N/A.

---

Jump to…

• Hardware Guide
• Prerequisites
• First-boot Basics
• PulseOS Configuration
• Notes & Extras
• Troubleshooting

Reference Docs

• home-assistant-photo-frame — Nest-style Lovelace photo frame + custom card
• mqtt-and-telemetry — MQTT buttons (Home/Update/Reboot) & diagnostic sensors
• voice-assistant — Wyoming pipelines, LLM providers, and real-time news/weather/sports intents
• assistant-commands — Built-in “no LLM needed” voice shortcuts (alarms, timers, news, etc.)
• troubleshooting — Pi 5 + Touch Display kiosk fixes (black strip, touch, autologin, etc.)
• notes-and-extras — Voice assistant tips, MQTT knobs, hardware accessories, boot splash notes, and other odds & ends
• public-photo-sources — Open-licensed image feeds (NASA, Smithsonian, Met, etc.) for pulse-photo-card
• config-reference — Comprehensive pulse.conf option list with defaults and usage notes

External interfaces (APIs, inputs/outputs)

• Configuration surface: docs/config-reference.md details every pulse.conf key and default.
• MQTT control & telemetry topics: docs/mqtt-and-telemetry.md.
• Voice assistant intents & CLI: docs/assistant-commands.md and docs/voice-assistant.md.

Hardware Guide

Supported hardware, recommended parts, and printable accessories

As of Nov 2025, $317 plus 3d printed parts (or buy/figure out a case) to build a single Pulse. Or choose your own components - anything that will work with Linux.

Raspberry Pi 5 — 16GB

• Specs: https://www.raspberrypi.com/products/raspberry-pi-5/
• Retailer: https://www.pishop.us/product/raspberry-pi-5-16gb/?src=raspberrypi
• Recommended add-ons:
  • Pi Active Cooler: https://www.pishop.us/product/raspberry-pi-active-cooler/?searchid=0&search_query=374-1
• Price (11/2025): $131 with active cooler

Pi Touch Display 2 — 7”

• Specs: https://www.raspberrypi.com/products/touch-display-2/
• Retailer: https://www.pishop.us/product/raspberry-pi-touch-display-2/
• Price (11/2025): $82

ReSpeaker Mic Array 3.0 (XVF3000)

• Specs: https://wiki.seeedstudio.com/respeaker_mic_array_v3.0/
• Retailer: https://www.seeedstudio.com/ReSpeaker-Mic-Array-v3-0.html
• Price (11/2025): $64

BoomPod Zero mini speaker

• Specs: https://boompodsusa.com/products/boompods-zero-mini-wireless-bluetooth-5-pocket-size-speaker
• Retailer: same
• Price (11/2025): $40

Desktop Case + Pi 5 Stand

• MakerWorld: https://makerworld.com/en/models/789481-desktop-case-for-raspberry-pi-7-touch-display-2

3d Print Models (see models/ directory)

• ReSpeaker Mic Array Plate (which I glue to the Pi case cover)
• ReSpeaker Mic Array Cover
• BoomPod Zero Cup (which I glue to one of the display leg stands - or both for two pods!)

---

0) Prerequisites

• Raspberry Pi 5/CM4/CM5 with Raspberry Pi Touch Display 2 (DSI ribbon in the “closer” socket).
• Fresh Raspberry Pi OS Lite (64-bit) (Trixie, at the moment) written to microSD - I'm using 128GB but it's only 20% full (so far).
  • Setup "pulse-" hostname and "pulse" user when imaging OS
  • Can also pre-setup networking, make sure SSH is on, enable auto-login
• Network connectivity (Ethernet or Wi‑Fi).
• SSH access (run sudo raspi-config nonint do_ssh 0 or enable via imager advanced options).

---

1) First‑boot basics

1. Update Raspberry Pi OS and install prerequisites.

   sudo apt update && sudo apt full-upgrade -y
   sudo apt install -y git gh neovim
   sudo chown pulse:pulse /opt

2. Clone PulseOS under /opt and open the repo.

   cd /opt
   git clone https://github.com/weirdtangent/pulse-os.git
   cd pulse-os

3. Create pulse.conf from the sample and edit it for this kiosk.

   cp pulse.conf.sample pulse.conf
   vi pulse.conf

4. Create a Pulse dashboard in Home Assistant (recommended).

   • From the HA sidebar, add a new dashboard named “Pulse” using the dashboard URL slug dashboard-pulse.
   • For the first tab/view, set the title to “Home” with the view URL slug home and add the Lovelace cards you want displayed.
   • Pulse defaults to http://homeassistant.local:8123/dashboard-pulse/home, so tweak the hostname if needed or point PULSE_URL elsewhere in the next step.

5. Run the setup script with a location slug (first boot only).

   ./setup.sh <location-name>

   By default setup.sh finishes by calling bin/tools/restart-services.sh so every kiosk service reloads without a reboot. Pass --no-restart if you’re iterating on a single unit and want to restart things manually (you can always run the helper script yourself later).

   Re-run ./setup.sh after changing pulse.conf or pulling new code (omit the location on repeat runs). The MQTT “Update” button performs the same update + setup flow remotely and inherits the automatic restart step.

---

PulseOS Configuration

Each kiosk reads /opt/pulse-os/pulse.conf. Copy the sample, edit the values that matter for this device, then rerun ./setup.sh.

cp /opt/pulse-os/pulse.conf.sample /opt/pulse-os/pulse.conf
vi /opt/pulse-os/pulse.conf

All keys are optional, but filling out the relevant sections keeps boot, kiosk, MQTT, and assistant services aligned with your environment. Refer to docs/config-reference.md for every available variable, its default, and practical usage notes.

🔒 Security tip: pulse.conf often contains API keys, MQTT credentials, and private calendar URLs. setup.sh automatically sets the file owner to PULSE_USER and applies chmod 600, but keep the repo staged under /opt (not your home directory) and never commit pulse.conf back to git or copy it into cloud backups without similar protections.

Quick config verification

After editing pulse.conf, run the connectivity check to confirm the services you referenced are reachable:

bin/tools/verify-conf.py --config /opt/pulse-os/pulse.conf

It loads the config (or the path you pass with --config) and:

• Connects to the MQTT broker using your credentials.
• Sends a single RFC5424 syslog line if remote logging is enabled.
• Calls each configured Wyoming endpoint (openWakeWord/Whisper/Piper) and, when possible, performs a short functional probe.
• Tests HOME_ASSISTANT_BASE_URL/HOME_ASSISTANT_TOKEN by calling /api/.

Any failure is printed with remediation text and the script exits non-zero so you can gate deployments on it if desired.

---

Notes & Extras

All of the voice-assistant tips, MQTT knobs, Home Assistant snippets, printable accessories, and boot splash notes now live in docs/notes-and-extras.md. Looking for the built-in wake-word shortcuts? See docs/assistant-commands.md.

Troubleshooting checklist

See the dedicated troubleshooting guide for the full Pi 5 + Touch Display checklist (black strip, touch calibration, autologin, etc.).

Contributors

• @weirdtangent

Buy Me A Coffee

Releases, versioning, and release notes

• Semantic versioning (major.minor.patch); version metadata is managed by release.config.js and tagged in git.
• Interim commits are pushed to main; formal releases are tagged and summarized in CHANGELOG.md.
• Release artifacts and source are delivered over HTTPS/SSH; verify tags and checksums where applicable.

Quality gates and analysis

• CI runs on every PR and main push: ruff check, black --check, pytest, dependency auditing, and CodeQL analysis.
• Static analysis (Ruff, CodeQL) is required before releases; medium+ findings must be fixed before publishing.
• Dynamic checks: pytest suite (with assertions enabled) runs per PR and release.

Build & Quality Status

Security Status