Adapters
Camera

Camera Streaming

Stream live video from USB webcams or Raspberry Pi Camera Modules directly to your Plexus dashboard. The agent auto-detects connected cameras and streams JPEG frames over WebSocket in real time.

Install

For USB cameras (OpenCV):

pip install plexus-agent[camera]

For Raspberry Pi Camera Module (v1, v2, v3, HQ Camera):

pip install plexus-agent[picamera]

Quick Start

The agent auto-detects cameras when you run plexus start or plexus run. No extra flags needed.

plexus start --key plx_xxxxx

When cameras are detected, the agent reports them to the dashboard. You can then start and stop video streams from the dashboard UI by adding a Video panel to any dashboard.

How It Works

  1. The agent scans for connected cameras on startup (Pi cameras first, then USB)
  2. Camera metadata (name, resolution, capabilities) is sent to the dashboard
  3. When you open a Video panel, the dashboard sends a start_camera command
  4. The agent captures frames at the configured frame rate, encodes as JPEG, and streams over WebSocket
  5. Frames are relayed through the PartyKit server to all connected browsers
  6. When the Video panel is closed, streaming stops automatically

Configuration

USB Camera

from plexus.cameras import USBCamera
 
camera = USBCamera(
    device_index=0,          # Camera index (0 = first, 1 = second)
    frame_rate=15.0,         # Frames per second (default: 15)
    resolution=(640, 480),   # Width x height (default: 640x480)
    quality=80,              # JPEG quality 1-100 (default: 80)
    camera_id="front-cam",   # Custom ID (default: "usb:0")
)

Raspberry Pi Camera

from plexus.cameras import PiCamera
 
camera = PiCamera(
    camera_num=0,            # Camera number (default: 0)
    frame_rate=30.0,         # Frames per second (default: 30)
    resolution=(1280, 720),  # Width x height (default: 1280x720)
    quality=85,              # JPEG quality 1-100 (default: 85)
    camera_id="pi-cam",      # Custom ID (default: "picam:0")
)

Parameters

ParameterTypeUSB DefaultPi DefaultDescription
frame_ratefloat15 fps30 fpsTarget frames per second
resolution(int, int)(640, 480)(1280, 720)Frame width and height in pixels
qualityint8085JPEG encoding quality (1-100). Lower = smaller frames, faster streaming
camera_idstr"usb:{index}""picam:{num}"Unique identifier for this camera
tagsdict{}{}Metadata tags attached to every frame

Auto-Detection

The agent scans for cameras automatically:

from plexus.cameras import scan_cameras
 
detected = scan_cameras()
for cam in detected:
    print(f"{cam.name}: {cam.device_id}")

Pi cameras are scanned first. Their V4L2 device indices are excluded from the USB scan to prevent conflicts between picamera2 and OpenCV accessing the same device.

Auto-Detection with Overrides

from plexus.cameras import auto_cameras
 
# Auto-detect all cameras with custom settings
hub = auto_cameras(
    frame_rate=10,            # Override FPS for all cameras
    resolution=(1024, 768),   # Override resolution for all
    quality=70,               # Override quality for all
)

Multi-Camera Setup

Use CameraHub to manage multiple cameras:

from plexus.cameras import CameraHub, USBCamera, PiCamera
 
hub = CameraHub()
hub.add(USBCamera(device_index=0, camera_id="front"))
hub.add(USBCamera(device_index=1, camera_id="rear"))
hub.add(PiCamera(camera_num=0, camera_id="overhead"))

Each camera streams independently and appears as a separate video source in the dashboard.

Dashboard Video Panel

To view a camera feed in the dashboard:

  1. Open a dashboard and click Add Panel
  2. Select Video as the panel type
  3. Choose the device and camera from the dropdowns
  4. The stream starts automatically

The video panel shows:

  • Live JPEG frames rendered in real time
  • A green pulsing indicator when streaming is active
  • Frame dimensions (e.g., 640x480)

Shared dashboard viewers can watch camera feeds in read-only mode without being able to start or stop streams.

CLI Flags

# Auto-detect cameras (default behavior)
plexus run
 
# Disable camera auto-detection
plexus run --no-cameras

Troubleshooting

USB camera not detected:

  • Check permissions: sudo usermod -aG video $USER (then log out and back in)
  • Verify the device exists: ls /dev/video*
  • Run plexus doctor to diagnose permission issues

Pi camera not detected:

  • Enable the camera interface: sudo raspi-config → Interface Options → Camera
  • Check libcamera is working: libcamera-hello --list-cameras
  • Ensure picamera2 is installed: pip install plexus-agent[picamera]

High latency or choppy video:

  • Lower the resolution: resolution=(320, 240)
  • Lower the frame rate: frame_rate=5
  • Lower JPEG quality: quality=50
  • Check your network bandwidth between the device and the Plexus server

Next Steps

MAVLinkSerial / GPS