Update object hunting docs

Author: 91volt

examples/object-hunting/README.md

@@ -1,12 +1,14 @@
 # Object Hunting
 
-The **Object Hunting** is an interactive scavenger hunt that uses real-time object detection. Players must locate specific physical objects in their environment using a USB camera connected to the Arduino UNO Q to win the game.
+The **Object Hunting Game** is an interactive scavenger hunt that uses real-time object detection. Players must locate specific physical objects in their environment using a USB camera connected to the Arduino UNO Q to win the game.
+
+**Note:** This example requires to be run using **Network Mode** or **Single-Board Computer (SBC) Mode**, since it requires a **USB-C® hub** and a **USB webcam**.
 
 ![Object Hunting Game Example](assets/docs_assets/thumbnail.png)
 
 ## Description
 
-This App creates an interactive game that recognizes real-world objects. It utilizes the `video_objectdetection` Brick to stream video from a USB webcam and perform continuous inference. The web interface challenges the user to find five specific items: **Book, Bottle, Chair, Cup, and Cell Phone**.
+This App creates an interactive game that recognizes real-world objects. It utilizes the `video_objectdetection` Brick to stream video from a USB webcam and perform continuous inference using the **YoloX Nano** model. The web interface challenges the user to find five specific items: **Book, Bottle, Chair, Cup, and Cell Phone**.
 
 Key features include:
 
@@ -34,19 +36,19 @@ The object hunting game example uses the following Bricks:
 ### Software
 
 - Arduino App Lab
-
-**Important:** A **USB-C® hub is mandatory** for this example to connect the USB Webcam. Consequently, this example must be run in **[Network Mode](learn/network-mode)** or **[SBC Mode](learn/single-board-computer)**.
-
+**Important:** A **USB-C® hub is mandatory** for this example to connect the USB Webcam.
 **Note:** You must connect the USB camera **before** running the App. If the camera is not connected or not detected, the App will fail to start.
 
 ## How to Use the Example
 
 1. **Hardware Setup**
    Connect your **USB Webcam** to a powered **USB-C® hub** attached to the UNO Q. Ensure the hub is powered to support the camera.
+     ![Hardware setup](assets/docs_assets/hardware-setup.png)
 
 2. **Run the App**
    Launch the App from Arduino App Lab.
    *Note: If the App stops immediately after clicking Run, check your USB camera connection.*
+   ![Arduino App Lab - Run App](assets/docs_assets/launch-app.png)
 
 3. **Access the Web Interface**
    Open the App in your browser at `<UNO-Q-IP-ADDRESS>:7000`. The interface will load, showing the game introduction and the video feed placeholder.
@@ -67,18 +69,30 @@ The object hunting game example uses the following Bricks:
 
 ## How it Works
 
-Once the App is running, it performs the following operations:
+The application relies on a continuous data pipeline between the hardware, the inference engine, and the web browser.
+
+**High-level data flow:**
+
+```
+   USB Camera   ──►   VideoObjectDetection   ──►   Inference Model (YoloX)
+                              │                           │
+                              │ (MJPEG Stream)            │ (Detection Events)
+                              ▼                           ▼
+                       Frontend (Browser)     ◄──    WebUI Brick
+                              │
+                              └──►   WebSocket (Threshold Control)
+```
 
 - **Video Streaming**: The `video_objectdetection` Brick captures video from the USB camera and hosts a low-latency stream on port `4912`. The frontend embeds this stream via an `<iframe>`.
-- **Inference**: The backend continuously runs an object detection model on the video frames.
+- **Inference**: The backend continuously runs the **YoloX Nano** object detection model on the video frames.
 - **Event Handling**: When objects are detected, the backend sends the labels to the frontend via WebSockets.
-- **Game Logic**: The frontend JavaScript compares the received labels against the target list (`['book', 'bottle', 'chair', 'cup', 'cell phone']`) and updates the game state.
+- **Game Logic**: The frontend JavaScript compares the received labels against the target list and updates the game state.
 
 ## Understanding the Code
 
-### 🔧 Backend 
+### 🔧 Backend (`main.py`)
 
-The Python® script initializes the detection engine and bridges the communication between the computer vision model and the web UI.
+The Python script initializes the detection engine and bridges the communication between the computer vision model and the web UI.
 
 - **Initialization**: Sets up the WebUI and the Video Object Detection engine.
 - **Threshold Control**: Listens for `override_th` messages from the UI to adjust how strict the model is when identifying objects.
@@ -105,53 +119,66 @@ def send_detections_to_ui(detections: dict):
 detection_stream.on_detect_all(send_detections_to_ui)
 ```
 
-### 🔧 Frontend 
-
-The web interface handles the game logic, video embedding, and user feedback.
+### 🔧 Frontend (`app.js`)
 
-- **Video Embedding**: The HTML loads the raw video stream provided by the backend on a specific port.
-
-```javascript
-const targetPort = 4912;
-const streamUrl = `http://${currentHostname}:${targetPort}/embed`;
-```
-
-- **Game State Management**: The JavaScript defines the targets and tracks progress.
+The web interface handles the game logic. It defines the specific objects required to win the game.
 
 ```javascript
 const targetObjects = ['book', 'bottle', 'chair', 'cup', 'cell phone'];
 let foundObjects = [];
-```
 
-- **Processing Detections**: When the backend sends a `detection` event, the script checks if the detected object is in the target list and hasn't been found yet. If it matches, it updates the UI and checks for a win condition.
-
-```javascript
 function handleDetection(detection) {
     const detectedObject = detection.content.toLowerCase();
 
     // Check if the detected item is a target and not yet found
     if (targetObjects.includes(detectedObject) && !foundObjects.includes(detectedObject)) {
         foundObjects.push(detectedObject);
-        
-        // Update UI to show item as found
-        const foundItem = document.getElementById(`obj-${detectedObject}`);
-        foundItem.classList.add('found');
-        
         updateFoundCounter();
         checkWinCondition();
     }
 }
 ```
 
-- **Win Condition**:
-
-```javascript
-function checkWinCondition() {
-    if (foundObjects.length === targetObjects.length) {
-        gameStarted = false;
-        // Hide video, show win screen
-        videoFeedContainer.classList.add('hidden');
-        winScreen.classList.remove('hidden');
-    }
-}
-```
+### 🛠️ Customizing the Game
+
+The default model used by the `video_objectdetection` Brick is **YoloX Nano**, trained on the **COCO dataset**. This means the camera can detect approximately 80 different types of objects, not just the five used in this example.
+
+**To change the objects you want to hunt:**
+
+1. **Choose new targets**: You can select any object from the [standard COCO dataset list](https://github.com/amikelive/coco-labels/blob/master/coco-labels-2014_2017.txt) (e.g., `person`, `keyboard`, `mouse`, `backpack`, `banana`).
+2. **Update the code**: Open `assets/app.js` and locate the `targetObjects` array:
+   ```javascript
+   const targetObjects = ['book', 'bottle', 'chair', 'cup', 'cell phone'];
+   ```
+3. **Replace the items**: Substitute the strings with your chosen object names from the COCO list.
+   ```javascript
+   const targetObjects = ['person', 'keyboard', 'mouse', 'laptop', 'backpack'];
+   ```
+4. (Optional) Update `assets/index.html` to change the icons and text displayed in the game introduction to match your new targets.
+
+## Troubleshooting
+
+### App fails to start or stops immediately
+If the application crashes right after launching, it is likely because the **USB Camera** is not detected.
+**Fix:**
+1. Ensure the camera is connected to a **powered USB-C hub**.
+2. Verify the hub has its external power supply connected (5 V, 3 A).
+3. Reconnect the camera and try running the App again.
+
+### Video stream is black or not loading
+If the game interface loads but the video area remains black or shows "Searching Webcam...":
+- **Browser Security:** Some browsers block mixed content or insecure frames. Ensure you are not blocking the iframe loading from port `4912`.
+- **Network:** Ensure your computer and the UNO Q are on the same network.
+- **Camera Status:** If the camera was disconnected while the App was running, you must restart the App.
+
+### Objects are not being detected
+If you are pointing the camera at an object but it doesn't register:
+- **Check the list:** Ensure the object is one of the targets defined in `app.js`.
+- **Adjust Confidence:** Lower the **Confidence Level** slider. If set too high (e.g., > 0.80), the model requires a perfect angle to trigger a detection.
+- **Lighting:** Ensure the object is well-lit. Shadows or darkness can prevent detection.
+- **Distance:** Move the camera closer or further away. The object should occupy a significant portion of the frame.
+
+### "Connection to the board lost" error
+If this message appears at the bottom of the screen:
+- The WebSocket connection has been severed.
+- **Fix:** Refresh the web page. If the error persists, check if the UNO Q is still powered on and connected to the network.