https://github.com/weirdtangent/pulse-os
Pulse Display Assistant is a Raspberry Pi kiosk OS for Home Assistant, delivering a live overlay of timers/alarms/reminders plus news, weather, sports, and an optional OpenAI/Gemini voice assistant.
https://github.com/weirdtangent/pulse-os
automation chromium display embedded-linux home-assistant home-automation iot kiosk maker-project mqtt-client raspberry-pi raspberry-pi-touchscreen smart-home systemd
Last synced: 4 months ago
JSON representation
Pulse Display Assistant is a Raspberry Pi kiosk OS for Home Assistant, delivering a live overlay of timers/alarms/reminders plus news, weather, sports, and an optional OpenAI/Gemini voice assistant.
- Host: GitHub
- URL: https://github.com/weirdtangent/pulse-os
- Owner: weirdtangent
- License: mit
- Created: 2025-11-04T19:30:01.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2026-04-01T22:51:09.000Z (4 months ago)
- Last Synced: 2026-04-02T05:03:26.146Z (4 months ago)
- Topics: automation, chromium, display, embedded-linux, home-assistant, home-automation, iot, kiosk, maker-project, mqtt-client, raspberry-pi, raspberry-pi-touchscreen, smart-home, systemd
- Language: Python
- Homepage:
- Size: 5.41 MB
- Stars: 13
- Watchers: 1
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
# 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](https://github.com/weirdtangent/pulse-os/issues) with repro details and expected behavior.
- Contribute: follow [`CONTRIBUTING.md`](CONTRIBUTING.md) and [`TESTING.md`](TESTING.md) for coding standards (Black 120 cols, Ruff) and required checks (ruff, black, pytest).
- Security reports: use the process in [`SECURITY.md`](SECURITY.md); please do not open public issues for vulnerabilities.
- CPE: not published / N/A.
---
## Jump to…
- [Hardware Guide](#hardware-guide)
- [Prerequisites](#0-prerequisites)
- [First-boot Basics](#1-firstboot-basics)
- [PulseOS Configuration](#pulseos-configuration)
- [Notes & Extras](#notes--extras)
- [Troubleshooting](#troubleshooting-checklist)
### Reference Docs
- [home-assistant-photo-frame](docs/home-assistant-photo-frame.md) — Nest-style Lovelace photo frame + custom card
- [mqtt-and-telemetry](docs/mqtt-and-telemetry.md) — MQTT buttons (Home/Update/Reboot) & diagnostic sensors
- [voice-assistant](docs/voice-assistant.md) — Wyoming pipelines, LLM providers, and real-time news/weather/sports intents
- [assistant-commands](docs/assistant-commands.md) — Built-in “no LLM needed” voice shortcuts (alarms, timers, news, etc.)
- [troubleshooting](docs/troubleshooting.md) — Pi 5 + Touch Display kiosk fixes (black strip, touch, autologin, etc.)
- [notes-and-extras](docs/notes-and-extras.md) — Voice assistant tips, MQTT knobs, hardware accessories, boot splash notes, and other odds & ends
- [public-photo-sources](docs/public-photo-sources.md) — Open-licensed image feeds (NASA, Smithsonian, Met, etc.) for `pulse-photo-card`
- [config-reference](docs/config-reference.md) — Comprehensive `pulse.conf` option list with defaults and usage notes
### External interfaces (APIs, inputs/outputs)
- Configuration surface: [`docs/config-reference.md`](docs/config-reference.md) details every `pulse.conf` key and default.
- MQTT control & telemetry topics: [`docs/mqtt-and-telemetry.md`](docs/mqtt-and-telemetry.md).
- Voice assistant intents & CLI: [`docs/assistant-commands.md`](docs/assistant-commands.md) and [`docs/voice-assistant.md`](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:
* Retailer:
* Recommended add-ons:
* Pi Active Cooler:
* Price (11/2025): $131 with active cooler
### Pi Touch Display 2 — 7”
* Specs:
* Retailer:
* Price (11/2025): $82
### ReSpeaker Mic Array 3.0 (XVF3000)
* Specs:
* Retailer:
* Price (11/2025): $64
### BoomPod Zero mini speaker
* Specs:
* Retailer: same
* Price (11/2025): $40
### Desktop Case + Pi 5 Stand
* MakerWorld:
### 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.**
```bash
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.**
```bash
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.**
```bash
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).**
```bash
./setup.sh
```
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`.
```bash
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](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:
```bash
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](docs/notes-and-extras.md). Looking for the built-in wake-word shortcuts? See [docs/assistant-commands.md](docs/assistant-commands.md).
## Troubleshooting checklist
See the dedicated [troubleshooting guide](docs/troubleshooting.md) for the full Pi 5 + Touch Display checklist (black strip, touch calibration, autologin, etc.).
## Contributors
- [@weirdtangent](https://github.com/weirdtangent)
### 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`](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
[](https://github.com/astral-sh/ruff)
[](https://github.com/psf/black)
### Security Status
[](https://github.com/weirdtangent/pulse-os/security/code-scanning)
[](https://scorecard.dev/viewer/?uri=github.com/weirdtangent/pulse-os)
[](https://www.bestpractices.dev/projects/11650)
