Skip to content
This repository was archived by the owner on Sep 30, 2026. It is now read-only.
snoackPublic archive

About

Show UniFi Protect or any RTSP security cameras on a screen from a Raspberry Pi, without a desktop or browser.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Viewwall

Warning

Viewwall is deprecated in favor of viewpie, which supersedes it and is where development continues. Please use Viewpie for new installations.

Viewwall hit two limits of its Python and GStreamer foundation:

  • No atomic presenter. Viewwall has two output backends, and each gives up something. kms-planes scans every viewport out on its own plane through its own kmssink, but the independent page flips share one refresh, capping each viewport at roughly the refresh rate divided by the number of viewports. compositor renders the wall in software, which gives up most of the benefit of hardware acceleration and costs a lot of CPU. The right design lies between the two: an atomic presenter that still scans each feed out on its own KMS plane, but commits all of them together once per refresh. That cannot be built in Python on top of GStreamer.
  • No hardware H.265 decoding on the Raspberry Pi. Current GStreamer does not support the Pi's HEVC decoder, so H.265 cameras fall back to software decoding.

Viewpie is written in Rust around one atomic commit for the whole wall, and decodes with FFmpeg's libav* libraries.

Show all your security cameras on one screen, on a Raspberry Pi.

Viewwall turns a Pi and a TV into a camera wall: a grid of live RTSP feeds, started at boot, that recovers on its own when a camera or the network drops out. It draws straight to the screen through DRM/KMS, so there is no desktop, no browser and no window manager.

Built and tested against UniFi Protect, and works with any camera or NVR that publishes RTSP.

+-------------+-------------+-------------+
|  driveway   |    porch    |   street    |
+-------------+-------------+-------------+
|    yard     |  doorbell   |   garage    |
+-------------+-------------+-------------+
|   shed      |   patio     |  side gate  |
+-------------+-------------+-------------+
  • Any layout. Viewports are rectangles in fractions of the screen, so one configuration follows a change of resolution.
  • Hardware decoding, no copying. Each feed is decoded once by the Pi's video hardware and scanned out on its own display plane. A Pi 3 sustains nine feeds at full camera framerate.
  • Rotation. A viewport can cycle through several cameras, keeping them all connected so switching is instant.
  • Unattended. Feeds reconnect on their own; systemd restarts the wall if it ever dies. It is meant to run for months on a shelf.

Quick start

You need a Raspberry Pi 3 or newer running Raspberry Pi OS Lite, a screen, and cameras that publish RTSP.

1. Install

Nothing needs configuring first: a current Raspberry Pi OS image works as it comes.

Download the .deb from releases:

sudo apt install ./viewwall_0.1.0-1_all.deb

2. Describe the wall

sudoedit /etc/viewwall/viewwall.toml
[feeds.driveway]
uri = "rtsp://192.168.1.1:7447/aBcDeFgHiJkLmNoP"

[feeds.porch]
uri = "rtsp://192.168.1.1:7447/QrStUvWxYzAbCdEf"

# Each viewport shows a camera, placed as fractions of the screen.
[[viewports]]
x = 0
y = 0
width = "1/2"
height = 1
feeds = ["driveway"]

[[viewports]]
x = "1/2"
y = 0
width = "1/2"
height = 1
feeds = ["porch"]

On UniFi Protect, enable RTSP per camera in the Protect app. The URL it shows needs two edits before it will play here:

rtsps://192.168.1.1:7441/aBcDeFgHiJkLmNoP?enableSrtp   <- what Protect shows
rtsp://192.168.1.1:7447/aBcDeFgHiJkLmNoP               <- what to configure

Drop ?enableSrtp, which asks for encrypted media Viewwall cannot decrypt, and switch rtsps:// on 7441 to rtsp:// on 7447. The stream id stays as it is, and there are no credentials. To keep TLS instead, leave the rtsps:// URL on 7441 and see RTSP and RTSPS -- but still drop ?enableSrtp.

Other cameras that want a login take it inline as rtsp://user:password@host/path.

3. Check the config

sudo -u viewwall viewwall -c /etc/viewwall/viewwall.toml validate

4. Start it

sudo systemctl enable --now viewwall

The wall appears within a few seconds. To watch what it is doing:

journalctl -u viewwall -f

Configuration

Anything omitted uses its default, so a working configuration is mostly feeds and viewports. A fuller example is in examples/viewwall.toml. An option Viewwall does not recognise is an error rather than a silent no-op, so a typo says so instead of leaving a setting at its default.

[[viewports]] — one table per viewport: a region of the screen showing one camera. Viewports have no names; logs and metrics identify one by its position in the file, counting from 1, and name the feed it is showing alongside.

Option Default Meaning
x, y required Where the viewport's top-left corner sits, as a fraction of the screen: "1/3", or a whole 0 or 1.
width, height required How much of the screen it covers, in the same units. A 3x3 wall is nine viewports of 1/3. The camera is stretched to fill it, deliberately: it avoids black bars around a doorbell camera that is not 16:9.
feeds required Feed names. Listing more than one rotates the viewport through them; every one stays connected and decoding, so a switch is instant rather than waiting for the stream to start, and unhealthy cameras are skipped.
rotate_seconds 8 Seconds between switches; must be positive. Ignored on a single-feed viewport.
display the only display Which display the viewport is on, by name. Only needed with more than one [displays.<name>] table, since otherwise there is a single display to be on: the one configured, or the first one connected when none is.

[feeds.<name>] — one table per camera.

Option Default Meaning
uri required rtsp:// or rtsps://. A ${VAR} placeholder is expanded from the environment. H.264 or H.265 is detected from the RTSP announcement.
latency_ms 150 Jitterbuffer depth. Raise it on a lossy network, at the cost of latency.
transport "tcp" The RTP transport: "tcp", "udp", "udp-mcast", or "auto" to negotiate one of the three with the server. TCP (default) was the only one to work reliably during testing using a Raspberry Pi 3 and UniFi NVR; udp and auto crashed within seconds and udp-mcast connected to nothing.
verify_tls true rtsps:// only. false accepts a self-signed certificate; the transport stays encrypted, the server is simply not verified.

[feed_defaults] — latency_ms, transport and verify_tls for any feed that does not set its own.

[displays.<name>] — one table per output, needed only to drive more than one screen. With none of these, the first connected output is used and the rest are left alone; [display_defaults] still applies to it, so setting a seam does not mean naming a screen.

Option Default Meaning
connector_id the first connected output Which output this is. Required only when more than one display is configured. With a single one the first connected output is driven and any others are left alone, which is the same choice made when there is no [displays] table at all. kmsprint -l lists them as Connector 0 (35) HDMI-A-1 (connected), where 35 is the id, and the startup log line names the ones in use. With several displays, which screen showed what would otherwise depend on probe order.
gap_px 0 Seam between viewports, in pixels. Made by trimming that pixel off the edge of the video rather than drawing over it, so the picture is never scaled and every plane stays on the cheap 1:1 path.
outer_margin_px 0 Inset from this screen's edges.
width, height active mode Overrides the detected resolution. Both or neither.
mode connector default Mode to drive the connector at, as "1280x720" or "1280x720@60". Without a refresh rate the driver picks one, which on a panel offering 1920x1080 at 120, 60, 50, 30 and 24 is whichever it resolves first -- 120 on the measured panel. Naming the rate is the only way to choose, and the compositor backend wants 60 rather than 120: it blends every output frame on the CPU, so twice the refresh is twice the work for no visible gain once every camera is already showing every frame it sends.

[display_defaults] — gap_px and outer_margin_px for any display that does not set its own, including the discovered one.

Each display is its own canvas: a viewport's position is a fraction of the screen it is on, not of some union of screens. A viewport cannot span two displays, because a KMS plane belongs to exactly one output.

[displays.hall]
connector_id = 35

[displays.office]
connector_id = 36
gap_px = 1

[[viewports]]
x = 0
y = 0
width = 1
height = 1
feeds = ["driveway"]
display = "hall"

[[viewports]]
x = 0
y = 0
width = "1/2"
height = "1/2"
feeds = ["porch"]
display = "office"

A feed may appear on both, and is still decoded once. The planes each display needs are worked out together, since on a Pi many planes can drive more than one output and a plane handed to one display is not available to the other.

[metrics]

Option Default Meaning
interval_seconds 60 How often to log per-viewport framerate and queue depth. 0 disables.

[drm] — the graphics card, which is one card however many displays.

Option Default Meaning
device detected DRM card to open. Displays are connectors within one card, not separate devices. Detected from the card that owns the connectors, which is card0 on a Pi 3 but card1 on a Pi 5; set it to pin one.
poll_interval_seconds 2 How often to re-probe the card for a resolution change. One probe reports every connector.
background "#000000" Color painted under the viewports as #RRGGBB, or "none" to leave the framebuffer console showing. "none" needs output_backend = "kms-planes": the compositor draws the whole screen, so no console is left behind it.
output_backend "kms-planes" How viewports reach the screen. See below.

Output backend

kms-planes gives every viewport its own KMS overlay plane and its own kmssink. The video path is zero-copy, but each sink issues a separate legacy drmModeSetPlane, and those serialise into one commit per vblank per CRTC: on a 60Hz output nine viewports share 60 commits a second and get about 6.7 each, whatever their cameras send. Raising the output to 120Hz doubles the budget at no CPU cost, which is why a high-refresh mode is worth choosing here.

compositor blends the whole wall into one frame and scans it out through a single kmssink on a single plane, so one commit carries every viewport and each tile is limited by its own feed rather than by its share of the commit budget. It costs a CPU blend of the full output frame.

Measured on a Pi 5 at 1920x1080, nine feeds of 640x360 (15-30 fps sources):

kms-planes @120Hz compositor @60Hz
per viewport 13.4 fps, uniform 13.7-29.9 fps, each at its camera's rate
CPU ~55% of one core ~70-80% of one core
planes used one per viewport one per display

The compositor figure is a range because run-to-run spread on a shared Pi is several points; treat it as "most of a core", not a precise number. A layout.gap_px above zero adds roughly fifteen points on top of it: the seam is cut from each source by a videocrop, and compositor never offers a crop meta, so that element copies every frame of every tile instead of passing it through. gap_px = 0 leaves the tiles abutting and costs nothing.

That same missing crop meta is fatal rather than merely expensive on a Pi 3, where the hardware decoder hands videocrop DMA_DRM caps: with nothing to fall back on it refuses the crop outright and every seamed viewport dies at startup with "Dowstream doesn't support crop for non-raw caps". The compositor backend there needs gap_px = 0, and is otherwise unmeasured on that board.

The compositor's cost scales with output resolution and refresh, not with the number of viewports: at 120Hz it blends twice as many frames for no visible gain once every camera is already showing every frame it sends. Pair it with a 60Hz mode. Capping the blend rate below the refresh was measured and changes nothing at 60Hz, so there is no setting for it.

kms-planes remains the default: it is the zero-copy path, it needs less CPU, and it is what the Pi 3 wall has run on. The compositor has not been measured on a Pi 3.

Two settings behave differently under the two backends. drm.background = "none" is refused with compositor, because a full-screen composited frame leaves no console to show through. And the compositor wants a lower refresh rate than kms-planes: see mode below.

Metrics

Every 60 seconds viewwall logs what each viewport is doing:

metrics viewport=2 feed=porch state=healthy queued_fps=29.6 decoded_fps=29.8 \
  window_s=60.0 presented_fps=7.4 sink_dropped=1327 queue_ms=45

The three rates follow one frame along the path, and a drop between any two names where it is being lost:

Field Where it is counted
decoded_fps Frames leaving the decoder.
queued_fps Buffers leaving the viewport's output queue toward its plane. A gap below decoded_fps is the leaky queue shedding frames the wall could not keep up with.
presented_fps Buffers the sink actually put on the KMS plane. This is what reaches the screen.
sink_dropped Buffers the sink discarded for arriving late against the clock, which is the difference between the two rates above.

Expect presented_fps to sit well below queued_fps on a full wall. Each plane is updated by its own drmModeSetPlane and the VC4 retires one per vblank, so the viewports share 60 updates a second between them: a nine-viewport wall measures about 7.4fps each, summing to 60. See the plane budget section of DESIGN.md.

queue_ms is how much video is waiting — a viewport sitting at 250ms is a quarter of a second behind live.

A rotating viewport that switched feeds during the interval is marked rotated=1, with window_s giving the shorter span the rates cover. Its rates and decoded_fps are measured over different spans and should not be compared.

Under systemd these are attached as structured journal fields, so they can be summarized without parsing the text:

journalctl -u viewwall -o json --output-fields=VW_VIEWPORT,VW_QUEUED_FPS,VW_PRESENTED_FPS \
  | jq -r 'select(.VW_VIEWPORT) | [.VW_VIEWPORT, .VW_QUEUED_FPS, .VW_PRESENTED_FPS] | @tsv'

To change the interval, or turn it off:

[metrics]
interval_seconds = 60   # 0 disables

Log level

log_level sets how much the wall says, as a top-level key:

log_level = "DEBUG"   # DEBUG, INFO, WARNING or ERROR; default INFO

--log-level overrides it, so a level can be forced without editing the file. DEBUG adds per-event detail -- crop and aspect decisions, GStreamer error detail, and the numbers behind each feed-recovery verdict. Nothing at that level runs per frame, so it costs little beyond journal volume.

RTSP and RTSPS

Feeds use rtsp:// over TCP by default (feed_defaults.transport = "tcp").

rtsps:// works. A UniFi Protect NVR presents a self-signed certificate, so certificate validation has to be relaxed:

[feeds.backyard]
uri = "rtsps://192.168.1.1:7441/aBcDeFgHiJkLmNoP"
verify_tls = false

verify_tls may be set per feed or in [feed_defaults], and applies only to rtsps:// URIs. It is a boolean rather than a set of modes: a partial validation mask looks like the right way to accept just a self-signed certificate, but GLib deprecated per-condition flags and this GStreamer treats any non-zero value as full validation. Measured against a Protect NVR, flags 122/126/127 all fail with "Could not open resource for reading and writing" and only 0 connects, so a partial mode would silently do nothing. With verify_tls = false the transport is still encrypted; the server is simply not verified. Viewwall logs a warning whenever a feed runs this way.

Protect offers both per camera: 7447 for plain RTSP and 7441 for RTSPS. The samples here use 7447, because on a LAN it is the better trade. RTSPS does not improve image quality or framerate, costs a little extra CPU for TLS on a Pi that has none to spare, and against a self-signed certificate it buys less than it appears to: verify_tls = false stops passive sniffing but not an active attacker, who can present their own certificate and be believed. That is close to the plain-RTSP threat model with extra steps.

RTSPS earns its keep when the feeds cross a network you do not control, or when the server has a certificate you can actually verify -- with verify_tls left at true, the guarantee is real.

SRTP is not supported: drop ?enableSrtp from the URL Protect shows. It is opt-in on both ports, so nothing else has to change -- SRTP encrypts the media payload, which is separate from whether the control channel uses TLS, and rtsps:// on 7441 works without it. Left on, the stream connects and then fails because the payload cannot be decrypted; Viewwall detects this from the negotiated SDP and stops that feed with a clear message rather than retrying forever. See DESIGN.md for what supporting it would involve.

Running in Docker

The wall writes directly to KMS overlay planes, so the container needs the host's DRM and V4L2 devices. It cannot render anything in an ordinary sandboxed container, and nothing else may hold DRM master — stop a native viewwall service before starting the container.

# compose.yaml
services:
  viewwall:
    image: ghcr.io/<owner>/viewwall:0.1.0
    restart: unless-stopped
    devices:
      # card0 on a Pi 3, card1 on a Pi 5, where card0 is the render-only v3d
      # node with no connectors. Check with: ls /sys/class/drm
      - /dev/dri/card0:/dev/dri/card0   # KMS output planes
      # A Pi 5 has no H.264 decoder and needs no video device for one; it
      # software-decodes with avdec_h264. /dev/video19 is its HEVC decoder.
      - /dev/video10:/dev/video10       # hardware H.264 decoder (Pi 3/4)
      # H.265 needs these too. v4l2slh265dec is a stateless decoder, and
      # GStreamer only registers one when it can reach the media controller
      # node that drives it: without them the element does not exist and an
      # H.265 feed fails to start, while the same feed works outside Docker.
      - /dev/media0:/dev/media0         # media controller (stateless codecs)
      - /dev/media1:/dev/media1
      - /dev/media2:/dev/media2
    group_add:
      # Numeric GIDs, not names: group names are resolved inside the container,
      # whose /etc/group has no video or render entry. Check yours with
      #   getent group video render
      - "44"    # video
      - "992"   # render
    volumes:
      - /etc/viewwall:/etc/viewwall:ro
    environment:
      # A "${PORCH_RTSP}" placeholder in viewwall.toml is expanded from the
      # environment, which keeps the credentials out of the config file and
      # lets Compose supply them.
      PORCH_RTSP: ${PORCH_RTSP}

Stop any native service first, or the container cannot take DRM master:

sudo systemctl stop viewwall
docker compose up -d

Verified on a Raspberry Pi 3 running Raspberry Pi OS Trixie: the container renders all nine planes from live cameras with the device nodes and two groups above.

Pass every /dev/videoN decoder node your Pi exposes if you are unsure which one GStreamer will pick; on a Pi 3 the H.264 decoder is /dev/video10, and on a Pi 5 the HEVC decoder is /dev/video19. Pass /dev/media* as well. A stateless decoder -- v4l2slh265dec, which is the only way viewwall decodes H.265 -- is registered by GStreamer only when it can reach the media controller node behind it, so without those an H.265 feed fails to start with "no supported decoder is available for H265" while the same feed plays on a native install.

A native systemd install is lighter than Docker on a Pi 3, and is the recommended deployment.

Supported hardware

Raspberry Pi 3, running Raspberry Pi OS. Developed and verified on a Pi 3 Model B+ with Raspberry Pi OS Trixie, which is what the kms-planes backend and its measurements describe.

A Pi 5 also works and is where the compositor backend was measured, but it is a different trade rather than a faster Pi: BCM2712 dropped the H.264 decoder block, so every feed is software-decoded with avdec_h264, and the DRM card that owns the connectors is card1. Nine feeds leave a Pi 3 around 76% idle on kms-planes; the same wall on a Pi 5 under compositor costs most of a core. A Pi 4 should work and is untested.

Older Pi models are not supported: they lack the KMS overlay planes the design depends on.

Other hardware, including x86, is out of scope for now. The design itself is not Pi-specific: the layout model, recovery logic, GStreamer graph and KMS output path would all port. Three things currently tie it to a Pi:

  • kms++-utils, used for KMS discovery, is packaged by Raspberry Pi OS rather than Debian, so the .deb cannot satisfy its dependencies on plain x86 Debian. The published image is built for linux/arm/v7 and linux/arm64.
  • Decoder selection prefers the Pi's V4L2 M2M decoders. H.264 falls back to software avdec_h264, so it would run on x86 but on the CPU; there is no VAAPI or NVDEC path.
  • A wall on the default kms-planes backend needs one overlay plane per viewport (compositor needs one per display instead). Intel and AMD display engines typically expose far fewer than the nine a 3x3 wall wants.

Supporting x86 properly would mean replacing the kmsprint shell-out with direct DRM queries and adding VAAPI to the decoder policy.

Troubleshooting

Nothing appears on screen. Check journalctl -u viewwall -n 50. "No unused YUV-capable KMS overlay planes found" means the display driver is not full KMS. Raspberry Pi OS enables it by default, so this points at a dtoverlay line in /boot/firmware/config.txt selecting the legacy or vc4-fkms-v3d driver; neither is supported.

One viewport is black. That camera is unreachable or still starting. Viewwall retries on its own, backing off up to 30 seconds; the log names the feed.

Every viewport is black. Viewwall logs no viewport is showing video at error level and reports it to systemd, so systemctl status viewwall shows it too. That is the NVR being unreachable, credentials having changed, or a transport the streams cannot use.

"A lot of buffers are being dropped" at --log-level DEBUG. GStreamer emits this from a late-buffer count alone, and a camera whose decoder holds and then releases frames in bursts trips it continuously without losing any. Check that viewport's fps in the metrics rather than trusting the warning; it is logged at debug level for this reason.

A viewport is behind the others. Check queue_ms in the metrics lines. Some cameras declare frame reordering in their H.264 stream, which makes the decoder hold frames and puts that viewport a quarter-second behind the rest. It is a camera-side setting; see DESIGN.md.

Feeds fail to start. The log names the feed and the reason. A camera that is unreachable is retried; one that keeps failing usually points at the URL, credentials, or a codec viewwall cannot decode on that model.

It worked, then stopped after adding cameras. A wall needs one display plane per viewport, and hardware runs out of them. The log reports a resource error naming the viewport that failed.

The wall restarted itself after a camera came back. A feed that connects, reports healthy, and dies within seconds -- three times in a row, and again after viewwall rebuilds that feed's branch -- is wedged on state a retry cannot reach. The log says so and names the feed, and the wall exits so the service manager gives it a clean process. A camera that is simply off or unreachable never triggers this; it retries indefinitely instead. If it keeps happening, the restarts spread out from five seconds to a minute apart rather than stopping, so the wall keeps showing whichever cameras are healthy.

How it works

DESIGN.md covers the media path, the recovery model, how viewports are resolved to pixels, the measurements behind the current settings, and the approaches that were tried and rejected.

Development

Unit tests cover configuration validation, fractional layout resolution, source-crop calculation, and KMS discovery parsing:

pytest -q

Live RTSP, V4L2 decoder, DMA-BUF, and KMS behavior must be tested on the Pi.

Building the artifacts

./scripts/build-deb.sh          # -> dist/viewwall_<version>-<rev>_all.deb
docker build -t viewwall:dev .  # needs an armhf/arm64 builder for a Pi

To cut a release, set the version in pyproject.toml, commit, then tag:

git tag v0.1.0 && git push origin v0.1.0

That runs the release workflow, which tests, builds the package, pushes a multi-arch image to GHCR ({{version}}, {{major}}.{{minor}} and latest), and creates a GitHub release with the .deb attached. The version comes from pyproject.toml rather than from the tag; the workflow compares the two and fails if they disagree.

The .deb is Architecture: all — it is pure Python, a unit file and a wrapper script, so one package serves every supported Pi. The Pi-specific part is its dependencies, not its contents.

After the first release only, make the GHCR package public, or pulls fail with a 403: a package pushed by GITHUB_TOKEN is private by default, and its visibility can only be set once the package exists. Find it under the repository's Packages, then Package settings → Change visibility. This is a one-time step and is independent of whether the repository itself is public.

License

GPL-3.0-or-later. Copyright Sebastian Noack.

About

Show UniFi Protect or any RTSP security cameras on a screen from a Raspberry Pi, without a desktop or browser.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages