.

Author: steveseguin

QUICK_START.md

@@ -2,26 +2,50 @@
 
 ## 1. Install
 
-On Raspberry Pi OS, Ubuntu, or Debian:
+On Raspberry Pi OS, Ubuntu, or Debian, run as your normal user with sudo access:
 
 ```bash
-curl -sSL https://raw.githubusercontent.com/steveseguin/raspberry_ninja/main/install.sh | bash
+cd ~
+curl -fL https://raw.githubusercontent.com/steveseguin/raspberry_ninja/main/install.sh -o install-raspberry-ninja.sh && \
+  bash install-raspberry-ninja.sh --non-interactive --runtime-only --skip-system-upgrade
 cd ~/raspberry_ninja
 ```
 
-## 2. Choose what this Pi should do
+Continue only after the installer succeeds. This installs runtime dependencies
+without development headers or a full OS upgrade. If you already have a clone,
+run `bash install.sh --non-interactive --runtime-only --skip-system-upgrade`
+from that directory instead.
+
+## 2. Set up a Raspberry Pi to start at boot
 
 ```bash
 sudo python3 tools/setup.py
 ```
 
-Choose **Show video on a TV** or **Send camera video**. Setup finds the camera,
-microphone, display mode, and safe video settings automatically, then makes the
-Pi start itself after a reboot.
+Choose **Show video on a TV** or **Send camera video**. Setup lists detected
+cameras and microphones, writes a configuration, and enables and starts a systemd
+service. Connect the camera or TV first. The selected video defaults may need
+adjustment for your camera's supported resolutions and frame rates.
 
 Use the same stream name and password at both ends. That is all most Raspberry
 Pi setups need.
 
+The guided service setup targets Raspberry Pi Linux systems with systemd. For
+Jetson, Orange Pi, desktops, or other platforms, use the
+[platform installation guides](installers/README.md) and manual commands.
+
+To check a guided sender (use `raspberry-ninja-viewer` for a receiver):
+
+```bash
+sudo systemctl status raspberry-ninja-sender
+sudo journalctl -u raspberry-ninja-sender -n 30 --no-pager
+```
+
+Re-run setup to change the stream name, password, or source; it restarts the
+selected service. Advanced service options are documented by
+`python3 tools/install_unattended.py --help` and its `sender --help` or
+`receiver --help` subcommands.
+
 ## Optional one-time test
 
 To publish a small test pattern without changing the saved setup:
@@ -35,5 +59,10 @@ python3 publish.py --test --h264 --noaudio \
 Open `https://vdo.ninja/?view=rn-test&password=false` and stop the test with
 Ctrl+C. Use a real password for anything beyond this first test.
 
+For a local software encode/decode check without publishing a stream, run
+`python3 tools/media_self_test.py`. Missing codecs are reported as skipped;
+a failed probe or no passing probes returns a nonzero exit status. This does
+not test the camera, hardware encoders, HDMI output, or network connectivity.
+
 If setup reports a problem, continue with [Troubleshooting](docs/troubleshooting.md).
 Advanced commands remain available in the [documentation index](docs/README.md).

docs/platform-compatibility.md

@@ -65,6 +65,10 @@ gst-inspect-1.0 libcamerasrc
 
 Use `--rpicam` only when `rpicamsrc` is present and its pipeline has been tested. Use `--libcamera --rpi` for the libcamera GStreamer path. Do not remove a working legacy path merely because a newer OS uses another name.
 
+The guided setup checks both camera-tool names and prefers `libcamerasrc` when
+available, including with `rpicam-hello`. The application rename does not imply
+that the GStreamer source was renamed to `rpicamsrc`; that is a separate backend.
+
 Official background: [Raspberry Pi camera software](https://www.raspberrypi.com/documentation/computers/camera_software.html).
 
 ## GStreamer version differences

tests/test_easy_setup.py

@@ -46,7 +46,50 @@ def test_csi_discovery_requires_camera_and_working_gstreamer_source(self):
             ]
         )
         camera = setup.discover_csi_camera(runner=lambda *_a, **_k: next(responses))
-        self.assertEqual(camera, ("csi:rpicam", "imx219"))
+        self.assertEqual(camera, ("csi:libcamera", "imx219"))
+
+    def test_csi_discovery_supports_tool_and_plugin_combinations(self):
+        for camera_tool in ("rpicam-hello", "libcamera-hello"):
+            for backend in ("libcamera", "rpicam"):
+                with self.subTest(tool=camera_tool, backend=backend):
+                    def runner(command, **_kwargs):
+                        if command == [camera_tool, "--list-cameras"]:
+                            return subprocess.CompletedProcess(
+                                command, 0, stdout="", stderr="0 : imx219 [sensor]"
+                            )
+                        if command == ["gst-inspect-1.0", backend + "src"]:
+                            return subprocess.CompletedProcess(command, 0)
+                        raise FileNotFoundError(command[0])
+
+                    self.assertEqual(
+                        setup.discover_csi_camera(runner=runner),
+                        ("csi:" + backend, "imx219"),
+                    )
+
+    def test_csi_discovery_rejects_failed_listing_and_missing_plugins(self):
+        for listing_code in (0, 1):
+            with self.subTest(listing_code=listing_code):
+                def runner(command, **_kwargs):
+                    if command[0] == "gst-inspect-1.0":
+                        self.assertEqual(listing_code, 0)
+                        return subprocess.CompletedProcess(command, 1)
+                    return subprocess.CompletedProcess(
+                        command, listing_code, stdout="0 : imx219 [sensor]", stderr=""
+                    )
+
+                self.assertIsNone(setup.discover_csi_camera(runner=runner))
+
+    def test_passwords_survive_argument_parsing_for_both_roles(self):
+        for password in ("--secret", " leading and trailing ", "a&b=c"):
+            for arguments in (
+                setup.build_receiver_arguments(Path("/opt/rn"), "test", password),
+                setup.build_sender_arguments(
+                    Path("/opt/rn"), "test", password, "csi:libcamera", None, None
+                ),
+            ):
+                with self.subTest(password=password, arguments=arguments):
+                    parsed = setup.install_unattended.create_parser().parse_args(arguments)
+                    self.assertEqual(parsed.password, password)
 
     def test_camera_probe_recognizes_common_driver_names(self):
         completed = subprocess.CompletedProcess(
@@ -119,7 +162,19 @@ def test_receiver_flow_installs_with_three_simple_answers(self, install, _displa
         arguments = install.call_args.args[0]
         self.assertIn("receiver", arguments)
         self.assertIn("living-room", arguments)
-        self.assertIn("secret", arguments)
+        self.assertIn("--password=secret", arguments)
+
+    @patch("tools.setup.display_connected", return_value=True)
+    @patch("tools.setup.install_unattended.main", return_value=0)
+    def test_receiver_flow_preserves_password_whitespace(self, install, _display):
+        answers = iter(["1", "living-room"])
+        with patch("builtins.print"):
+            setup.main(
+                input_fn=lambda _prompt: next(answers),
+                password_fn=lambda _prompt: " secret ",
+            )
+        parsed = setup.install_unattended.create_parser().parse_args(install.call_args.args[0])
+        self.assertEqual(parsed.password, " secret ")
 
     @patch("tools.setup.display_connected", return_value=True)
     @patch("tools.setup.install_unattended.main", side_effect=RuntimeError("service failed"))

tests/test_install_unattended.py

@@ -1,7 +1,7 @@
 import argparse
 import tempfile
 import unittest
-from pathlib import Path
+from pathlib import Path, PurePosixPath
 from types import SimpleNamespace
 from unittest.mock import Mock
 
@@ -22,9 +22,9 @@ def test_receiver_config_keeps_credentials_out_of_unit(self):
             service_name=args.service_name,
             description="Receiver",
             user="steve",
-            repo_dir=Path("/home/steve/raspberry ninja"),
-            config_path=Path("/etc/raspberry-ninja/viewer.json"),
-            python_path=Path("/usr/bin/python3"),
+            repo_dir=PurePosixPath("/home/steve/raspberry ninja"),
+            config_path=PurePosixPath("/etc/raspberry-ninja/viewer.json"),
+            python_path=PurePosixPath("/usr/bin/python3"),
         )
 
         self.assertEqual(config["view"], "illinois-tv")
@@ -90,6 +90,18 @@ def test_raw_sender_config_is_preserved(self):
         self.assertTrue(config["raw"])
         self.assertEqual(config["format"], "YUY2")
 
+    def test_raw_format_selects_raw_capture_without_hidden_flag(self):
+        for capture_format in ("YUYV", "YUY2"):
+            with self.subTest(capture_format=capture_format):
+                args = self.parse(
+                    "sender", "--stream-id", "raw-camera",
+                    "--camera", "/dev/video0", "--allow-missing-device",
+                    "--format", capture_format,
+                )
+                config = install_unattended.build_config(args)
+                self.assertTrue(config["raw"])
+                self.assertEqual(config["format"], "YUY2")
+
     def test_csi_sender_config_uses_selected_camera_stack(self):
         args = self.parse(
             "sender",

tools/install_unattended.py

@@ -117,10 +117,10 @@ def build_config(args: argparse.Namespace) -> Dict[str, Any]:
         config["rpicam"] = True
     else:
         config["v4l2"] = args.camera
-        if args.raw:
+        if args.raw or args.format in {"YUYV", "YUY2"}:
             config["raw"] = True
         if args.format:
-            config["format"] = args.format
+            config["format"] = "YUY2" if args.format == "YUYV" else args.format
     if args.audio_device:
         config["alsa"] = args.audio_device
         config["audiobitrate"] = args.audio_bitrate

tools/setup.py

@@ -88,11 +88,9 @@ def discover_csi_camera(
     *,
     runner: Callable[..., subprocess.CompletedProcess] = subprocess.run,
 ) -> Optional[Tuple[str, str]]:
-    backends = (
-        ("rpicam", "rpicam-hello", "rpicamsrc"),
-        ("libcamera", "libcamera-hello", "libcamerasrc"),
-    )
-    for backend, camera_tool, source_element in backends:
+    # The camera applications were renamed; the libcamera GStreamer element
+    # was not. Probe the tools independently of the source plugin names.
+    for camera_tool in ("rpicam-hello", "libcamera-hello"):
         try:
             cameras = runner(
                 [camera_tool, "--list-cameras"],
@@ -103,20 +101,27 @@ def discover_csi_camera(
             )
             output = f"{cameras.stdout}\n{cameras.stderr}"
             camera_match = CSI_CAMERA_RE.search(output)
-            if not camera_match:
+            if cameras.returncode != 0 or not camera_match:
                 continue
-            plugin = runner(
-                ["gst-inspect-1.0", source_element],
-                check=False,
-                stdout=subprocess.DEVNULL,
-                stderr=subprocess.DEVNULL,
-                timeout=8,
-            )
         except (OSError, subprocess.TimeoutExpired):
             continue
-        if plugin.returncode == 0:
-            label = camera_match.group("label").split("[")[0].strip()
-            return (f"{CSI_SOURCE_PREFIX}{backend}", label or "Raspberry Pi Camera")
+        for backend, source_element in (
+            ("libcamera", "libcamerasrc"),
+            ("rpicam", "rpicamsrc"),
+        ):
+            try:
+                plugin = runner(
+                    ["gst-inspect-1.0", source_element],
+                    check=False,
+                    stdout=subprocess.DEVNULL,
+                    stderr=subprocess.DEVNULL,
+                    timeout=8,
+                )
+            except (OSError, subprocess.TimeoutExpired):
+                continue
+            if plugin.returncode == 0:
+                label = camera_match.group("label").split("[")[0].strip()
+                return (f"{CSI_SOURCE_PREFIX}{backend}", label or "Raspberry Pi Camera")
     return None
 
 
@@ -193,8 +198,7 @@ def build_receiver_arguments(repo: Path, stream_id: str, password: str) -> List[
     return [
         "--repo",
         str(repo),
-        "--password",
-        password,
+        f"--password={password}",
         "receiver",
         "--stream-id",
         stream_id,
@@ -219,8 +223,7 @@ def build_sender_arguments(
     arguments = [
         "--repo",
         str(repo),
-        "--password",
-        password,
+        f"--password={password}",
         "sender",
         "--stream-id",
         stream_id,
@@ -248,7 +251,7 @@ def main(
     input_fn: Callable[[str], str] = input,
     password_fn: Callable[[str], str] = getpass.getpass,
 ) -> int:
-    parser = argparse.ArgumentParser(add_help=False)
+    parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--inventory", action="store_true", help=argparse.SUPPRESS)
     options = parser.parse_args(list(argv or []))
     if options.inventory:
@@ -272,7 +275,7 @@ def main(
         input_fn=input_fn,
     )
     stream_id = ask_stream_id(input_fn=input_fn)
-    password = password_fn("Stream password: ").strip()
+    password = password_fn("Stream password: ")
     if not password:
         print("A password is required.", file=sys.stderr)
         return 2