Skip to content

Added a simple, mqtt configurable notification overlay#72

Merged
starbrightlab merged 2 commits into
starbrightlab:mainfrom
Jakkumn:topic/notifications
Jun 24, 2026
Merged

Added a simple, mqtt configurable notification overlay#72
starbrightlab merged 2 commits into
starbrightlab:mainfrom
Jakkumn:topic/notifications

Conversation

@Jakkumn

@Jakkumn Jakkumn commented Jun 23, 2026

Copy link
Copy Markdown
Contributor

Tested on a Portal+ (2nd gen)
Adds the ability to pop up a notification, from mqtt, that can display a photo, play a sound, and perform an intent navigation.
Additionally, you can play just a sound in isolation without a notification pop up.
F1
F2
F3

Example use case: User has a doorbell camera that is wired for talk back in Home Assistant. Instead of overriding current user action on screen, a notification appears that plays a sound and contains a photo and description of the interruption. User can decide to select the notification and be navigated to a target dashboard to interact as needed.

Example use case for just sound notification: User has a driveway sensor but no camera/image. Sensor fires and informs portal to play an audible notification.

The notification sound was validated against DND and is attached to the STREAM_ALARM volume control which is not linked to the standard user volume control/buttons.

2 available notification submittal paths. Path 1 uses home assistants default notification capabilities which is limited in what it can send; it can only send a message. Path 2 is direct mqtt message submittal and allows for more configuration, such as notification position, media to play, etc.

@starbrightlab

Copy link
Copy Markdown
Owner

Thank you for this, it's an excellent first contribution. The quality bar here is high: the design doc reasons all the way through the Portal volume quirk, DND behavior, audio-focus ducking, and the boot race before a line of code; the inSampleSize subsample guard shows you were thinking about the Gen-1 Portal heap specifically; and the retain-bit drop is a genuinely sharp defense against phantom-doorbell-on-reconnect. Test coverage on the parser is thorough and everything builds and passes clean locally. The two-track HA integration (discoverable notify.send_message for simple alerts, raw mqtt.publish for rich payloads) is exactly the right shape.

Merging this. There are a handful of small finishing touches that we'll take on ourselves as a follow-up, recorded here so the full picture is visible. None of them are blockers and none change the design:

  1. Tap routing through openTarget currently also re-publishes the open entity's retained state, so tapping a notify rewrites the Open entity in HA. We'll split the routing core from the state echo on our side, since it touches how the Open entity contract is consumed downstream.
  2. The single-player audio-focus request can leak or be abandoned early when two sounds fire close together (the "two notifies 50ms apart" case in your own validation plan). Easy fix, but we want to verify it on a physical Portal.
  3. A few leftover comments in SoundPlayer still reference STREAM_NOTIFICATION, whereas the final code routes via USAGE_ALARM (which is correct, and the main inline block explains why well). Comment scrub only.
  4. The Track 2 example in the design doc uses "duration": 8000, but duration is parsed as seconds (the smart-home.md example correctly uses 8). One-line doc fix.

We'll also file a follow-up to add a body-size cap on the image fetch. It's safe under the trusted-LAN model you documented, but cheap insurance worth having.

Really nice work. Looking forward to more.

@starbrightlab starbrightlab merged commit 8ba1769 into starbrightlab:main Jun 24, 2026
3 checks passed
starbrightlab added a commit that referenced this pull request Jun 24, 2026
Small post-merge fixes to the notification feature plus a CI repair:

- MqttPublisher: split openTarget into a pure routeTarget() (dispatch only)
  and the open/state echo, so a notify on_tap no longer rewrites the "Open"
  text entity's retained HA state.
- SoundPlayer: abandon any held audio focus before requesting again, so a
  second chime can't orphan the previous focus request and leave STREAM_MUSIC
  ducked. Refresh stale STREAM_NOTIFICATION comments to match USAGE_ALARM.
- docs: fix duration example (8000 -> 8 seconds) in the design doc.
- ci(tests.yml): pin setup-android packages to platform-tools; the action's
  default `tools` package archive now fails to download and breaks setup.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants