If pip install fails, try pip3 install ... instead, or use a virtual environment:

python3 -m venv bonicbot-env
source bonicbot-env/bin/activate   # On Windows: bonicbot-env\Scripts\activate
pip install bonicbot-bridge opencv-python numpy

1. Launch the BonicBot simulation:

   ros2 launch my_bot robot_system.launch.py use_sim_time:=true world:=obsworld.sdf use_real_camera:=True

   • use_real_camera:=True — the camera feed comes from your laptop’s webcam, while the robot’s body and motion are still simulated. This is the easiest way to test detection, since you can just hold whatever you want detected up to your laptop camera.
   • use_real_camera:=False — the camera feed comes from Gazebo instead (i.e. whatever the simulated camera sees inside the simulated world).

2. Once the simulation is running, use localhost as the host instead of a physical IP address:

   with BonicBot(host="localhost") as bot:

3. Everything else in the code — enabling face detection, drawing boxes, reading bot.get_faces() — works the same way, since the simulation exposes the same interface as a real robot. This path is mainly useful for exploring the lesson without hardware on hand; if you have a real BonicBot, connecting to its actual IP address is the recommended way to go through this lesson.

• Imports — time is used to pause briefly while waiting for YOLO to load; cv2 (OpenCV) handles drawing and displaying video; numpy supports the underlying image arrays; BonicBot is the SDK class that talks to the robot.
• draw_detections(frame, detections) — Takes a raw camera frame and the list of detections, then draws a green rectangle and a text label (class name + confidence percentage) for each detected object. Coordinates arrive normalized (0–1), so the function converts them to actual pixel positions using the frame’s width and height before drawing.
• with BonicBot(host='[IP_ADDRESS]') as bot: — Opens a connection to your robot. Using with ensures the connection is cleanly closed even if the program crashes or is interrupted.
• bot.system.start_camera() / bot.start_camera() / bot.camera.wait_for_image(timeout=5.0) — Purpose of this block: Initializes the robot connection context, powers on the camera hardware, starts streaming live video frames over the bridge, and waits up to 5 seconds for the first valid image frame before moving forward.
• bot.enable_detection("yolo") — Tells the robot to load and activate its YOLO object-detection model.
• while not bot.vision.yolo_enabled: time.sleep(0.1) — Loops in short 0.1-second waits until the robot confirms the YOLO model has finished loading and is active.
• Main while True loop — Continuously grabs the latest frame, fetches the current list of detections, draws boxes/labels on a copy of the frame, and shows it in a window named “BonicBot Vision”.
• cv2.waitKey(1) & 0xFF == ord("q") — Checks every loop iteration whether the q key was pressed; if so, the loop breaks and the program moves to cleanup.
• Cleanup (cv2.destroyAllWindows(), bot.disable_detection(), bot.stop_camera(), bot.system.stop_camera()) — Closes the video window, turns off YOLO detection, and shuts down the camera stream so the robot isn’t left running unnecessarily.

Visual Output:

Terminal Output:

{'class': 'person', 'confidence': 0.91, 'bbox': [0.52, 0.44, 0.18, 0.36]}

Your exact numbers will differ based on what’s in front of the camera. bbox is normalized [cx, cy, w, h] (0–1 range), so [0.52, 0.44, 0.18, 0.36] means roughly centered, slightly right and up. If nothing is in frame, you’ll see Nothing detected yet instead.

YOLO (“You Only Look Once”) is a family of models that scan an entire image in a single pass through a convolutional neural network, rather than sliding a window across the image and checking each spot separately. The network divides the image into a grid, and for each grid cell it predicts candidate bounding boxes, a confidence score, and class probabilities all at once. Overlapping boxes for the same object are then cleaned up with a step called non-max suppression, which keeps only the highest-confidence box and discards duplicates. YOLO models are typically trained on the COCO dataset, which is where the 80 object classes come from.

This explains the general, publicly documented YOLO architecture — it does not describe bonicbot-bridge’s exact internal pipeline (thresholds, pre/post-processing choices, etc.), which isn’t publicly documented beyond the model='yolov8n' default parameter you can pass to enable_detection().

class_filter takes a string matching one of the 80 COCO class names — try 'person', 'chair', or 'bottle'.