> For the complete documentation index, see [llms.txt](https://docs.theseus.us/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.theseus.us/cyclops/developers/raspberry-pi-camera-v2-integration.md). # Raspberry Pi Camera V2 Integration {% hint style="warning" %} This is ONLY for MIPI camera integration. If you are using the USB camera, you do not need to follow this page. {% endhint %} This guide takes a freshly built Cyclops device and enables a MIPI camera for the main video source. The commands are meant to be copy & paste, with only a few steps to get the camera running. ### Before you start #### Supported sensors | Sensor | `--sensor` value | Notes | | --------------------------------- | ------------------- | ------------------------------------------------- | | IMX219 (Camera Module 2 / clones) | `imx219` | Default; flight-validated | | IMX708 (Camera Module 3) | `imx708` | Autofocus module | | IMX477 (HQ Camera) | `imx477` | Interchangeable-lens | | OV9281 / IMX296 (global shutter) | `ov9281` / `imx296` | Best for fast motion (no rolling-shutter "jello") | Other Pi-supported sensors generally work too — pass their overlay name to `--sensor`. Vendor sensors may need a vendor overlay, driver, or tuning file. #### Software prerequisites * **Ubuntu 24.04** on the Pi 5 (2GB) with **Cyclops (v1.20.0)** installed. * **Vozilla (v2.8.0)** on your GCS. ### Step 1 — Connect the camera Power off the Pi, then connect the MIPI camera into the CAM0 port on the Pi. Then power on the Pi. ### Step 2 — Run the one-shot installer On the Pi, run the installer: {% hint style="info" %} This command defaults to the Camera Module 2 sensor (imx219) and expects the connection to be to the CAM0 port. Check the [#install-script-flags](#install-script-flags "mention") section to see what flags are available for this script. {% endhint %} ```bash curl -fsSL https://packages.theseus.us/mipi-install.sh | sudo bash ```
### Pre-flight calibration {% hint style="danger" %} **Calibrate Camera distortion before relying on navigation\\** Please use the [Camera Calibration](/cyclops/vehicle-integration/camera-calibration.md) to calibrate the camera intrinsic before flying the MIPI camera. {% endhint %} Verify the exposure mode is set to "Auto" or "Short" in the Lab Settings. This setting will change the exposure and is flight ready! If you are comfortable manually changing them, check the [#exposure-and-motion-blur](#exposure-and-motion-blur "mention") section to understand how to configure this.
### Exposure and motion blur Motion blur scales with the shutter (exposure) time: while the shutter is open, a moving aircraft smears the scene across the sensor. The 3 modes you can select are below: | Mode | Behaviour | Use when | | -------- | ---------------------------------------------------------------------------------------- | -------------------------- | | `auto` | libcamera default AE; may pick long shutters (more blur) in dim light | Stationary / bench testing | | `short` | AE biased toward a short shutter + higher gain (`AeExposureMode=Short`); still adapts | Light varies during flight | | `manual` | Pins `ExposureTime`/`AnalogueGain` (`AeEnable=False`); hard blur cap, no auto-brightness | Bright, consistent light | #### Editing exposure from Vozilla (applies live) **Settings → Lab → MIPI Exposure** lets you change the mode and, in manual mode, the shutter (µs) and gain. You can see these changes live within the Live Feed in Vozilla. #### Other levers to reduce motion blur * **Add light** — the IMX219 has a small fixed aperture, so short shutters need it. * **Use a global-shutter sensor** (OV9281, IMX296). The IMX219 is rolling shutter; under fast motion it also adds "jello" skew that a short shutter cannot remove — a global-shutter sensor is the hardware fix. #### Install Script Flags
FlagOptionEffect
--sensor NAMEimx219, imx708, imx477, imx296Overlay/sensor to configure (default imx219)
--connector NAMECAM0, CAM1Change the port the camera is connected to (default CAM0)
--no-rebootDo not reboot after installing (a reboot is required for installation to complete)
--no-activateDo not active the MIPI service
Example usage of these flags for a Camera Module 3 connected to the CAM1 port: ```bash curl -fsSL https://packages.theseus.us/mipi-install.sh | sudo bash -s -- --sensor imx708 --connector cam1 ``` ### Command cheat-sheet ```bash # Install / build the camera stack (first time) curl -fsSL https://packages.theseus.us/mipi-install.sh | sudo bash #Install / build the camera stack with a specified sensor and connector port curl -fsSL https://packages.theseus.us/mipi-install.sh | sudo bash -s -- --sensor imx708 --connector cam1 # Verify the stack only setup-mipi-camera.sh --verify-only rpicam-hello --list-cameras # Smoke-test the publisher + subscriber mipi_camera_publisher.py --config /usr/etc/vns-sdk/components/mipi_camera/camera_params.yaml --frames 30 cyclops_camera_subscriber.py --topic S1/cama --print-every 1 # Switch camera source sudo enable-mipi-camera.sh # MIPI sudo enable-mipi-camera.sh --source usb # USB # Watch the active publisher journalctl -u mipi-camera.service -f ``` ### Troubleshooting * Vozilla shows no camera connected: * Ensure you have the MIPI camera connected to the CAM0 port, and the ribbon is firmly seated in the port. Next, ensure that the camera stack is working by running this command: ```bash setup-mipi-camera.sh --verify-only ``` If this produces an error like this: ``` File "/usr/lib/vns-sdk/camera_publisher/cyclops_camera_ecal.py", line 349, in _resolve_schema_path Jun 16 21:48:59 clop-69 python3[12317]: raise FileNotFoundError(f"could not find image.capnp; searched: {searched}") Jun 16 21:48:59 clop-69 python3[12317]: FileNotFoundError: could not find image.capnp; searched: /usr/share/vns-sdk/capnp/image.capnp, /usr/share/vns-sdk/capnp/image.capnp, /usr/lib/vns-sdk/capnp/image.capnp, /usr/components/capnp/src/image.capnp, /usr/lib/vns-sdk/camera_publisher/capnp/image.capnp ``` Then run the following command to immediately fix it: ```bash sudo mkdir -p /etc/systemd/system/mipi-camera.service.d printf '[Service]\nEnvironment="VNS_CAPNP_SCHEMA_DIR=/usr/include/capnp"\n' \ | sudo tee /etc/systemd/system/mipi-camera.service.d/10-capnp-schema.conf sudo systemctl daemon-reload sudo systemctl restart mipi-camera.service ``` * Live Feed Black: * If the live feed is black, you may be on outdated dependencies like theseus-edge-api or Vozilla. Ensure you have updated to the latest versions of both. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.theseus.us/cyclops/developers/raspberry-pi-camera-v2-integration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.