Add read-only camera identification from MJPEG stream

README.md

@@ -21,12 +21,31 @@ dump to your device.
 
 ## First identify your camera
 
-The known failure affects the `EF-S7-V1.0.30B` camera family. A newer
-`EF-S7-V1.0.30D` revision uses different hardware and software and is not
-affected by this particular problem.
+The known failure affects one 8 MiB flash-layout variant of the
+`EF-S7-V1.0.30B` camera family. An earlier 16 MiB 30B variant uses materially
+different hardware and firmware. A newer `EF-S7-V1.0.30D` revision also uses
+different hardware and software and is not affected by this particular
+problem.
 
 Do this identification before building a USB cable, buying a programmer, or
-running the tools.
+running a repair operation.
+
+If the camera feed still works, start with the read-only stream check. Install
+[`cc2camera`](docs/INSTALLATION.md), find the printer's IP address or hostname,
+and run:
+
+```sh
+cc2camera identify-camera PRINTER
+```
+
+For example:
+
+```sh
+cc2camera identify-camera 192.168.1.50
+```
+
+If the stream is unavailable, the signature is unknown, or you want authoritative
+visual confirmation, inspect the hardware:
 
 1. Power the printer off and unplug it from mains power.
 2. Remove the camera module from the printer by undoing its single mounting
@@ -39,18 +58,25 @@ unclear, remove the two housing screws and check the complete PCB revision.
 
 ![TX5110 processor on a newer CC2 camera](docs/images/ef-s7-v1.0.30d-tx5110.jpg)
 
-| Identification | What is known |
-|---|---|
-| `EF-S7-V1.0.30B` / Ingenic T23 | This is the family on which the failure has been observed. Continue below. |
-| `EF-S7-V1.0.30D` / likely TX5110 | This revision is not affected by the known failure. This guide does not apply. |
-| Any other revision or processor | It has not been investigated. We do not know whether it is affected, and this guide does not apply. |
+The four-digit PCB manufacturing code appears to use `WWYY` week/year order.
+It is useful supporting evidence, but is not a safe cutoff on its own: component
+or firmware changes may not align exactly with calendar weeks.
+
+| Identification | Observed manufacturing codes | What is known |
+|---|---|---|
+| `EF-S7-V1.0.30B` / Ingenic T23 / 8 MiB `ZB25VQ64` family | `0226`, `0526` (two units), `1526` | This is the supported layout on which the failure has been observed. Continue below. |
+| `EF-S7-V1.0.30B` / Ingenic T23 / 16 MiB `P25Q128H` family | `4025` | This early layout is materially different. The known erase defect has not been established on it, and the current fix does not apply. |
+| `EF-S7-V1.0.30D` / likely TX5110 | Not established | This revision is not affected by the known failure. This guide does not apply. |
+| Any other revision, processor or flash layout | Not established | It has not been investigated. We do not know whether it is affected, and this guide does not apply. |
 
 ![EF-S7-V1.0.30D PCB marking](docs/images/ef-s7-v1.0.30d-revision.png)
 
 Photographs of the `EF-S7-V1.0.30B` board are available in the
 [OpenCentauri camera documentation](https://docs.opencentauri.cc/hardware/CC2/camera/).
-The processor marking is a quick screening aid; the full PCB marking is the
-authoritative visual identification.
+The stream fingerprint is a convenient read-only family-identification aid.
+The complete hardware markings and the tool's firmware and flash-layout checks
+determine whether a 30B camera is supported. Never bypass a refusal because a
+date code or stream signature appears to match.
 
 ## Choose the path that matches your camera
 

cc2camera/cli.py

@@ -12,6 +12,7 @@
 
 from . import __version__
 from . import image as image_tools
+from . import stream_identify
 from .display import invocation
 from .startup import install_startup
 from .restore_prepare import prepare_restore, validate_preparation_image
@@ -125,6 +126,48 @@ def command_info(args) -> int:
     return 0
 
 
+def command_identify_camera(args) -> int:
+    """Identify a known camera family from the printer's read-only MJPEG stream."""
+
+    try:
+        identification = stream_identify.identify_camera_stream(
+            args.printer, timeout=args.timeout
+        )
+    except stream_identify.StreamIdentificationError as exc:
+        raise ProtocolError(str(exc)) from exc
+    if identification.family is None:
+        raise ProtocolError(
+            "camera stream signature is not recognized; camera revision remains unknown"
+        )
+
+    print(f"Camera stream matches: {identification.family}")
+    print(f"Frames checked: {identification.frames_checked} consistent JPEG frames")
+    if identification.family == "EF-S7-V1.0.30B":
+        print(
+            "Evidence: this encoder signature has been observed on two independent "
+            "known 30B cameras."
+        )
+        print(
+            "30B includes more than one flash-layout variant. The affected 8 MiB "
+            "variant has been observed with PCB date codes 0226, 0526 and 1526; "
+            "an earlier 4025 unit uses a different, unsupported 16 MiB layout."
+        )
+        print(
+            "The stream cannot distinguish those variants. Date codes are supporting "
+            "evidence only; do not bypass the tool's firmware and flash-layout checks."
+        )
+    else:
+        print(
+            "Evidence: this encoder signature has been observed on one known 30D camera."
+        )
+        print("The known 30B camera failure has not been observed on the 30D family.")
+    print(
+        "Stream fingerprinting is a read-only family-identification aid; hardware "
+        "markings and the validated firmware layout determine whether the fix applies."
+    )
+    return 0
+
+
 def command_backup(args) -> int:
     output = Path(args.output)
     # Reject a non-atomic destination form before spending time on any physical
@@ -372,8 +415,8 @@ def progress(done: int, total: int) -> None:
         if remaining <= 0:
             raise ProtocolError(
                 "post-restore ADB availability timeout expired before the "
-                "temporary start. No HID ADB-start command was sent, and the "
-                "restore is not post-verified"
+                "temporary start. No HID ADB-start command was sent, and "
+                "the restore is not post-verified"
             )
         try:
             start_adb_through_upload_command()
@@ -442,6 +485,19 @@ def parser() -> argparse.ArgumentParser:
     info = commands.add_parser("device-info", parents=[common], help="validate root ADB and show flash layout; read-only")
     info.set_defaults(func=command_info)
 
+    identify = commands.add_parser(
+        "identify-camera",
+        help="identify a known 30B/30D camera from the printer MJPEG stream; read-only",
+    )
+    identify.add_argument("printer", help="printer hostname or IP address")
+    identify.add_argument(
+        "--timeout",
+        type=_positive_finite_duration,
+        default=stream_identify.DEFAULT_TIMEOUT,
+        help="HTTP stream timeout in seconds (default: 5)",
+    )
+    identify.set_defaults(func=command_identify_camera)
+
     backup = commands.add_parser("backup", parents=[common], help="save three consecutive identical flash reads; read-only")
     backup.add_argument("output", help="new backup archive ending in .zip")
     backup.add_argument("--accept-bootloader-sha256", type=_sha256_argument,