Repurpose your Mycroft Mark II as a Home Assistant voice satellite with touchscreen kiosk display.

Powered by Home Assistant Assist — you choose the pipeline.

mark2-assist installs everything needed to use a Mycroft Mark II as a fully featured Home Assistant voice satellite: voice integration via Linux Voice Assistant (ESPHome protocol), local wake word detection, touchscreen HA dashboard, animated face, clock+weather, LED ring, volume buttons and overlay, MQTT sensors, and optional audio streaming.

The voice pipeline runs entirely through Home Assistant Assist — meaning you choose what powers each step. Wake word detection runs locally on the device. STT, TTS and conversation can be anything HA supports: fully local (Whisper + Piper, no cloud required), via Nabu Casa, or AI-powered using OpenAI, Claude, OVOS, or any other conversation agent HA integrates with.

Note: Pi 5 is partially supported (separate SJ201 overlays exist) but untested.

• SJ201 hardware driver — VocalFusion kernel module, XVF-3510 firmware flash, TAS5806 amp init, WirePlumber profile
• Linux Voice Assistant — Voice satellite using linux-voice-assistant (ESPHome protocol). Includes local OWW wake word detection, timers, announcements and continue-conversation. Replaces the deprecated wyoming-satellite.
• Touchscreen kiosk — Weston Wayland compositor + Chromium in kiosk mode showing your HA dashboard
• Face event bridge — Monitors LVA states via HA API, writes /tmp/mark2-face-event.json for HUD overlays
• mark2-status — CLI command showing all service states, audio levels, HA connection and satellite state

Modules are selected during install via a checklist. Defaults are marked with ✓.

Without the homeassistant module the touchscreen still shows the animated face and clock — Mark II works as a pure voice satellite without any dashboard.

Before running the installer you need:

1. Raspberry Pi OS Lite Trixie (64-bit) flashed to SD card via Raspberry Pi Imager
   • Enable SSH and set username/password in Imager advanced settings
2. SSH access to the device on your local network
3. Home Assistant running on your local network
4. HA Long-Lived Access Token — for MQTT sensors and passive clock+weather display
   • In HA: Profile (bottom left) → Long-Lived Access Tokens → Create token

After running mark2-hardware-setup.sh and rebooting, run the hardware test to verify all components before proceeding with satellite/kiosk installation:

./mark2-hardware-test.sh

The test covers all Mark II hardware components interactively:

If any tests fail, fix them before running ./install.sh — the installer also offers to run the hardware test automatically after reboot.

Non-interactive mode (for scripted use):

./mark2-hardware-test.sh --auto

git clone https://github.com/andlo/mark2-assist
cd mark2-assist
./install.sh

The installer will:

1. Ask all questions upfront (HA URL, token, MQTT credentials, which modules to install)
2. Run hardware setup and reboot automatically
3. Resume after reboot and install Linux Voice Assistant + kiosk
4. Install your chosen optional modules
5. Reboot to the finished system

Total time: 20–40 minutes depending on network speed.

The Mark II kiosk displays the HA dashboard inside an iframe. By default HA blocks this with X-Frame-Options: SAMEORIGIN. Add this to your configuration.yaml and restart HA — without it the touchscreen shows a blank page instead of your dashboard:

http:
  use_x_frame_options: false

After the first kiosk setup the touchscreen may prompt for login. To log in automatically, also add the following to configuration.yaml:

homeassistant:
  auth_providers:
    - type: homeassistant
    - type: trusted_networks
      trusted_networks:
        - 192.168.1.x        # Replace with your Mark II's exact IP address
      trusted_users:
        192.168.1.x:         # Same IP as above
          - YOUR_USER_ID     # Find in HA: Settings → People → click user → ID in URL
      allow_bypass_login: true

How to find your user ID: In HA go to Settings → People → click your user. The URL ends with /config/users/edit/abc123def456 — that last part is your user ID.

How to find Mark II's IP:

hostname -I

How to edit configuration.yaml in HA: Use the Studio Code Server add-on or File Editor add-on. Navigate to /config/configuration.yaml and add both blocks above.

After restarting HA and rebooting Mark II, the dashboard loads automatically — no keyboard needed.

Security note: use_x_frame_options: false allows any page on your local network to embed your HA frontend in an iframe. It does not remove authentication. For most home setups this is perfectly safe. allow_bypass_login: true grants passwordless access from that specific IP only — using the exact device IP (not a subnet) limits this to your Mark II. Always keep - type: homeassistant as the first provider so you can still log in from other devices with a password.

See docs/HA_SETUP.md for full step-by-step instructions.

After installation Mark II announces itself on the network via Zeroconf/mDNS using the ESPHome protocol. Home Assistant will discover it automatically and show a notification to add it as an ESPHome device — no manual configuration needed.

If auto-discovery doesn't appear, add it manually:

1. Settings → Devices & Services → Add Integration
2. Search for ESPHome
3. Host: <Mark II IP address> — Port: 6053

Mark II will appear as your hostname (e.g. Nabu-1) under ESPHome devices and is immediately ready to use as an Assist satellite.

Set the voice pipeline: In HA go to Settings → Voice Assistants → your Mark II device → select which pipeline to use (e.g. "preferred", "Whisper+Piper local", "Claude", etc).

Say your wake word to test it.

Default wake word is "Ok Nabu".

To change the wake word after installation:

nano ~/.config/systemd/user/lva.service
# Edit the --wake-model value
systemctl --user daemon-reload
systemctl --user restart lva

Run the update script to update everything at once:

cd ~/mark2-assist
./update.sh

This updates system packages, mark2-assist scripts, Linux Voice Assistant, and restarts all services. LVA setup only re-runs if new commits were pulled.

Optional flags:

• --skip-apt — skip system package update
• --skip-lva — skip Linux Voice Assistant update
• --skip-restart — skip service restart
• --yes — non-interactive, no confirmation prompt

sudo apt update && sudo apt upgrade

A safe weekly update runs automatically every Sunday at 03:00 via /etc/cron.d/mark2-updates. It runs in two steps:

1. apt upgrade — system packages
2. update.sh --skip-apt --yes — mark2-assist scripts + LVA (git pull + setup if new commits)

The log is written to /var/log/mark2-updates.log.

After any kernel update the VocalFusion audio driver is automatically rebuilt by mark2-vocalfusion-watchdog.service before the next boot — no manual action needed.

cd ~/mark2-assist
git pull

Re-run the relevant setup script to apply changes:

./mark2-satellite-setup.sh   # Update kiosk/LVA configuration
./mark2-hardware-setup.sh    # Update hardware/driver configuration (rare)

Individual modules can be re-run at any time:

bash modules/ui.sh
bash modules/mqtt-sensors.sh
# etc.

cd ~/lva && git pull
rm -rf .venv && python3 script/setup
systemctl --user restart lva

cd ~/mark2-assist
./uninstall.sh

This removes:

• All mark2-assist systemd user services (LVA, kiosk, LEDs, face, overlay, MQTT, etc.)
• Installed packages (Chromium, weston, snapcast, shairport-sync, mpd, etc.)
• Configuration files in ~/.config/mark2/, ~/.config/mark2-kiosk/, etc.
• Weston/labwc autostart from ~/.bash_profile
• Auto-login getty override in /etc/systemd/system/[email protected]/

It does not remove:

• The VocalFusion kernel module (rebooting clears it from memory; .ko file stays)
• Boot overlay entries in /boot/firmware/config.txt (remove manually if needed)
• The ~/lva directory
• The mark2-assist git repository itself

Touchscreen is black after boot

grep vc4-kms-dsi-waveshare /boot/firmware/config.txt
# Should show: dtoverlay=vc4-kms-dsi-waveshare-800x480
# If missing: ./mark2-hardware-setup.sh && sudo reboot

LVA not showing in HA

systemctl --user status lva
journalctl --user -u lva -n 50

Test microphone directly

arecord -D plughw:CARD=sj201,DEV=1 -r 16000 -c 1 -f S16_LE -d 3 /tmp/test.wav
aplay /tmp/test.wav

HA dashboard shows login screen instead of auto-login

• Verify trusted_networks is configured in configuration.yaml (see above)
• Verify the IP in config matches Mark II's actual IP exactly (not a subnet)
• Restart HA after any configuration.yaml change

Kiosk not starting after reboot

cat /tmp/mark2-startup.log
cat /tmp/weston.log

Check all service statuses at a glance

mark2-status

Or individually:

systemctl --user status lva mark2-volume-buttons mark2-face-events mark2-led-events mark2-leds
sudo systemctl status mark2-leds

See the docs/ directory for detailed technical documentation:

• docs/HISTORY.md — History of Mark II, Mycroft, OVOS and HA Assist
• docs/INSTALL_SH.md — Install script architecture and flow
• docs/HARDWARE_SETUP.md — Hardware setup technical deep dive
• docs/SATELLITE_SETUP.md — Linux Voice Assistant setup deep dive
• docs/MODULES.md — All optional modules documented in detail
• docs/HA_INTEGRATION.md — HA companion integration spec
• docs/HA_SETUP.md — HA user, trusted network auto-login, and dashboard setup
• docs/mark2-dashboard.yaml — Ready-to-paste Mark II dashboard YAML

Issues are tracked on GitHub: https://github.com/andlo/mark2-assist/issues

GPL-3.0 — see LICENSE for details.

This project uses code adapted from OpenVoiceOS/ovos-installer (Apache 2.0) for the SJ201 hardware setup routines.