Merge pull request #414 from DeepwaterExploration/kernel-doc

Add Documentation for Kernel Issue
DeepwaterExploration · Sep 30, 2024 · 7abf327 · 7abf327
2 parents ff94a7f + 8a6d608
commit 7abf327
Show file tree

Hide file tree

Showing 2 changed files with 59 additions and 2 deletions.
diff --git a/docs/kernel-uvc-issue.md b/docs/kernel-uvc-issue.md
@@ -0,0 +1,35 @@
+# Linux Kernel UVC Driver Issues with Multiple Cameras
+
+This project addresses challenges encountered when using multiple USB 2.0 cameras with Linux-based systems, particularly focusing on the UVC (USB Video Class) driver in the Linux kernel.
+
+## Problem Overview
+
+The primary issue arises when attempting to capture video in compressed formats from multiple USB 2.0 cameras. Despite USB 2.0's theoretical maximum bandwidth of 480 MB/s, problems occur even when the actual bandwidth usage is significantly lower.
+
+### Key Points:
+
+- Issues persist even with cameras using built-in H.264 compression and low bitrates.
+- System crashes occur non-deterministically, often before reaching bandwidth saturation.
+- The problem is influenced by the XHCI host controller and its bandwidth reporting to the UVC driver.
+
+## Observed Behavior
+
+In our testing, using multiple cameras set to 10 Mbps bitrate led to system crashes before reaching the theoretical bandwidth limit. The exact point of failure varies and depends on the specific hardware configuration.
+
+## Potential Solutions
+
+### 1. VL805 XHCI Host Controller
+
+- Extensively optimized by Raspberry Pi for improved performance with multiple USB cameras.
+- Available as HATs for embedded computers and add-in cards for desktop x86 machines.
+- Generally offers more consistent performance.
+
+### 2. Kernel Patch
+
+- Modifies the reported bandwidth from the camera to be lower (within the UVC driver).
+- Can potentially alleviate issues in some configurations.
+- Can result in significantly more dropped frames
+
+## Contributing
+
+We welcome contributions to help resolve this issue. Please submit an issue.
diff --git a/frontend/src/layouts/cameras/index.tsx b/frontend/src/layouts/cameras/index.tsx
@@ -130,8 +130,30 @@ const DevicesLayout = () => {
                     let gstErrorMessage = message.data as GstErrorMessage;
                     stopStreamUpdate(gstErrorMessage.bus_info);
                     enqueueSnackbar(
-                        `GStreamer Error Occurred: ${gstErrorMessage.bus_info} - This is likely a known issue with the kernel, please read our docs site for more details`,
-                        { variant: "error", autoHideDuration: 5000 }
+                        <span>
+                            GStreamer Error Occurred: {gstErrorMessage.bus_info}{" "}
+                            - This is likely a known issue with the kernel,
+                            please click for more details.
+                        </span>,
+                        {
+                            variant: "error",
+                            autoHideDuration: 5000,
+                            action: () => (
+                                <a
+                                    href='https://dwe.ai/kernel-issue'
+                                    target='_blank'
+                                    style={{
+                                        color: "white",
+                                        textDecoration: "none",
+                                        padding: "8px 16px",
+                                        display: "block",
+                                        width: "100%",
+                                    }}
+                                >
+                                    Learn More
+                                </a>
+                            ),
+                        }
                     );
                     break;
             }