---
title: Doorbell Popup
description: Open a Home Assistant camera popup from a doorbell or motion entity.
sidebar:
  order: 9
---

`doorbell-popup` opens a Home Assistant more-info camera popup as an Omarchy webapp and positions it as a floating Hyprland window. It can run once, or watch a Home Assistant entity and open the popup when that entity turns on.

## Host bindings

Both public host overrides expose a permanent open-only popup on:

```text
SUPER+ALT+C
```

Both hosts use the same mobile-sized bottom-right geometry on the active workspace's monitor. Nothing is forced to a host-specific monitor or workspace.

## Defaults

The script defaults to:

| Setting | Default |
| --- | --- |
| Motion entity | `input_boolean.doorbell` |
| Camera entity | `camera.front_door_snapshot` |
| Home Assistant URL | `http://homeassistant.local:8123` |
| Target workspace | Active workspace |
| Size | `380x500` |
| Duration | `20` seconds |

The popup URL is built as:

```text
<base-url>/lovelace/home?more-info-entity-id=<camera-entity>
```

## Open once

Open the popup and exit:

```bash
doorbell-popup --open-only
```

Keep it open instead of scheduling the auto-close timer:

```bash
doorbell-popup --open-only --no-auto-close
```

Focus the popup after opening or repositioning:

```bash
doorbell-popup --open-only --focus-popup
```

## Watch mode

Run without `--open-only` to watch the motion entity:

```bash
doorbell-popup
```

Watch mode uses:

```bash
go-automate ha bridge watch entity --bar-json --icon '' input_boolean.doorbell
```

When the emitted JSON has class `on`, the popup opens or repositions.
The Omarchy Shell Home Assistant service keeps this watcher loaded in the background through `ha-module-bar doorbell`; it does not add a visible dashboard row.

## Positioning

`doorbell-popup` uses the focused monitor by default, keeping the popup on the active workspace. Explicit flags override that:

- `--monitor <name>` targets that monitor.
- `--workspace <id>` moves the popup to that workspace and uses its monitor.

`doorbell-popup` delegates geometry to `launch-floating-webapp`, the same global command used by shell webapp clicks. It places the exact launched window in the target monitor's bottom-right corner and accounts for output scale and reserved areas.

## Useful overrides

```bash
doorbell-popup --open-only --monitor DP-1 --width 380 --height 500
doorbell-popup --entity input_boolean.doorbell --camera-entity camera.front_door_snapshot
doorbell-popup --base-url http://homeassistant.local:8123 --workspace 1
doorbell-popup --duration 30 --margin 20 --bottom-margin 12
```

Numeric values must be positive integers.

## Test without a real event

Simulate one on event:

```bash
doorbell-popup --simulate-event on --simulate-exit
```

Force the startup simulation path:

```bash
doorbell-popup --force-motion-true --simulate-exit
```

## State

The script stores the last popup address at:

```text
${XDG_RUNTIME_DIR:-/tmp}/doorbell-popup.address
```

If that address still exists, the script repositions the existing popup instead of opening a duplicate. If the address is stale, it removes the file.

## Recovery flow

1. Test with `doorbell-popup --open-only` first.
2. Add `--monitor`, `--width`, and `--height` until placement is right.
3. Test the event path with `--simulate-event on --simulate-exit`.
4. Run watch mode only after the open-once path works.


## Troubleshooting

If the script exits immediately, check required commands:

```bash
command -v go-automate hyprctl jq launch-floating-webapp
```

If placement is on the wrong monitor, pass `--monitor <name>` and verify monitor names with:

```bash
hyprctl -j monitors
```

If no event opens the popup, check the entity stream directly:

```bash
go-automate ha bridge watch entity --bar-json --icon '' input_boolean.doorbell
```

If the popup keeps reusing a dead address, remove the runtime file:

```bash
rm -f "${XDG_RUNTIME_DIR:-/tmp}/doorbell-popup.address"
```