MAVLINKHUD
Download App MAVLink HUD for Android

SET_CAMERA_ZOOM

ID: 531

Summary

The SET_CAMERA_ZOOM command controls the focal length of an onboard camera during a mission. It allows for both incremental (rate-based) and absolute (percentage-based) zoom adjustments, enabling detailed inspections or wide-area reconnaissance from the same mission script.

Status

Supported (All Vehicles with AP_Camera enabled)

Directionality

  • RX (Receive): The vehicle receives this command as part of a mission upload or as a direct command from the GCS.

Mission Storage (AP_Mission)

  • Zoom Type (Param 1):
    • 0: Step (Not supported in storage).
    • 1: Continuous (Rate-based).
    • 2: Range (Percentage-based 0-100).
  • Zoom Value (Param 2): The value corresponding to the requested type.
  • Packing: Stored in the set_camera_zoom content struct.

Execution (Engineer's View)

Camera Driver Interaction

The command is routed through the AP_Camera library (AP_Camera.cpp).

  1. Rate-Based Zoom: If Continuous (1) is selected, the autopilot commands the lens motor to move at a specific speed. This is typically used with gimbal-integrated cameras where the operator wants to zoom in "until clear."
  2. Percentage Zoom: If Range (2) is selected, the autopilot maps the 0.0-100.0 input to the camera's internal zoom range ($Z_{min} \to Z_{max}$).
  3. Backend Support: This command works with MAVLink-enabled cameras (like SToRM32 or Tarot), DroneCAN cameras, and specialized drivers (like the Gremsy or Sony cameras). If the camera backend does not support zoom, the command is ignored.
  • param1 (Type): 0:Step, 1:Continuous, 2:Range.
  • param2 (Value): Rate (speed) or Percentage.
  • param3 to param7: Unused.

Theory: Magnification vs. Resolution

Zooming in does not increase the sensor's physical resolution; it changes the Field of View (FOV).

  • GSD Impact: Doubling the zoom ($2\times$) effectively halves the Ground Sample Distance (GSD), assuming the altitude remains constant.
  • Vibration Sensitivity: As FOV decreases (Zoom increases), the image becomes exponentially more sensitive to high-frequency vibration ($Z_{sens} \propto \frac{1}{\text{FOV}}$). This often requires the gimbal's PID gains to be adjusted dynamically (handled automatically by advanced backends).

Practical Use Cases

  1. In-Mission Target Detail:
    • Scenario: A drone is surveying a fence. It detects a breach at a waypoint.
    • Action: SET_CAMERA_ZOOM (Type: 2, Value: 80%). The drone zooms in to capture high-detail evidence before continuing the survey.
  2. Dynamic Reconnaissance:
    • Scenario: A search-and-rescue plane is looking for a boat.
    • Action: The plane orbits at $1\times$ zoom to cover the area. Once a suspect object is found, it uses a script to trigger SET_CAMERA_ZOOM to $10\times$ for confirmation.

Key Parameters

  • CAM_TYPE: Selection of camera hardware.
  • MNT1_TYPE: Often required as gimbals handle the physical lens motors.

Key Codebase Locations

SET_CAMERA_FOCUS

ID: 532

Summary

The SET_CAMERA_FOCUS command manages the focus state of an onboard camera. It supports triggering Auto-Focus (AF) routines or setting manual focus levels, ensuring sharp imagery for automated inspections where the distance to the subject varies.

Status

Supported (All Vehicles with AP_Camera enabled)

Directionality

  • RX (Receive): The vehicle receives this command as part of a mission upload or as a direct command from the GCS.

Mission Storage (AP_Mission)

  • Focus Type (Param 1):
    • 0: Auto.
    • 1: Continuous (Manual rate).
    • 2: Range (Manual percentage 0-100).
  • Focus Value (Param 2): The value corresponding to the manual types.
  • Packing: Stored in the set_camera_focus content struct.

Execution (Engineer's View)

Focus Management

The command is processed by the AP_Camera library (AP_Camera.cpp).

  1. Auto-Focus Trigger: If Auto (0) is selected, ArduPilot commands the camera backend to perform a "One-shot AF" or "Continuous AF" depending on the camera's internal capabilities.
  2. Manual Overrides: If Range (2) is selected, ArduPilot maps the input to the lens's focal range ($F_{min} \to F_{max}$).
  3. Lens Compatibility: This command requires a camera with an electronically controlled focus motor (e.g., Sony block cameras, Gremsy-integrated sensors). Fixed-focus mapping cameras (like those used for photogrammetry) will ignore this command.
  • param1 (Type): 0:Auto, 1:Continuous, 2:Range, 3:Meters (Rarely supported).
  • param2 (Value): Rate or Percentage.
  • param3 to param7: Unused.

Theory: The Circle of Confusion

Focusing is the process of minimizing the Circle of Confusion ($c$) on the image sensor.

  • Depth of Field (DOF): At high zoom levels, the DOF becomes extremely shallow.
  • Vibration: Out-of-focus images cannot be corrected in post-processing. SET_CAMERA_FOCUS is used to "Lock" focus before a high-vibration segment to prevent the camera's internal AF from "hunting" due to motion blur.

Practical Use Cases

  1. Macro Inspection:
    • Scenario: A drone is inspecting a weld on a bridge at a distance of 1.5 meters.
    • Action: SET_CAMERA_FOCUS (Auto) followed by IMAGE_START_CAPTURE.
  2. Infinity Lock:
    • Scenario: Mapping from 100m altitude.
    • Action: Mission starts with SET_CAMERA_FOCUS (Range: 100%) to lock the lens at infinity, preventing hunting during flight.

Key Parameters

  • CAM_TYPE: Selection of camera hardware.

Key Codebase Locations

SET_CAMERA_SOURCE

ID: 534

Summary

The SET_CAMERA_SOURCE command allows the mission to dynamically switch between different sensors (lenses) on a multi-sensor camera system. This is common on modern dual-sensor payloads that feature both a visual (RGB) and a thermal (EO/IR) sensor.

Status

Supported (All Vehicles with AP_Camera enabled)

Directionality

  • RX (Receive): The vehicle receives this command as part of a mission upload or as a direct command.

Mission Storage (AP_Mission)

  • Instance (Param 1): The camera ID (1-6). 0 for "All."
  • Primary Source (Param 2): Selection for the primary stream (e.g., RGB).
  • Secondary Source (Param 3): Selection for the secondary stream (e.g., IR).
  • Packing: Stored in the set_camera_source content struct.

Execution (Engineer's View)

Multicam Logic

The command is handled by AP_Camera::set_camera_source (AP_Camera.cpp).

  1. Index Translation: ArduPilot maps "Camera 1" to the first available hardware driver.
  2. Source Selection: The autopilot sends a command to the camera backend (MAVLink or specialized driver) to reconfigure the video stream or the image capture target.
  3. Use Cases:
    • Switching from Wide-Angle to Telephoto on a triple-lens system.
    • Switching from Visual to Night-Vision (Thermal) for a search leg.
  • param1 (Instance): Camera instance number.
  • param2 (Primary): 0:No change, 1:RGB, 2:IR, 3:NDVI.
  • param3 (Secondary): Same as above.
  • param4 to param7: Unused.

Theory: Sensor Fusion

In modern autonomous flight, the "Source" is not just a video feed; it defines the vehicle's Primary Intelligence Input.

  • RGB: Used for photogrammetry and human monitoring.
  • IR: Used for finding heat signatures (SAR) or hot-spots (Industrial Inspection).
  • The Switch: SET_CAMERA_SOURCE allows a single drone to perform two missions in one flight by reconfiguring its brain for the task at hand.

Practical Use Cases

  1. Thermal Inspection:
    • Scenario: Inspecting high-voltage lines.
    • Action: Mission flies to the pole. SET_CAMERA_SOURCE (IR) is used to check for heat, then SET_CAMERA_SOURCE (RGB) is used to take high-res visual confirmation of the hardware.
  2. Multi-Spectrally Survey:
    • Scenario: Mapping a field for crop health.
    • Action: Mission alternates sources to capture both RGB and NDVI (Normalized Difference Vegetation Index) data.

Key Parameters

  • CAM_TYPE: Selection of camera hardware.

Key Codebase Locations

IMAGE_START_CAPTURE (2000) / IMAGE_STOP_CAPTURE

ID: 2001

Summary

The IMAGE_START_CAPTURE and IMAGE_STOP_CAPTURE commands provide precise control over high-resolution still image acquisition. They support single-shot, interval-based (time), and burst-based capture modes, making them the standard choice for professional survey and reconnaissance missions.

Status

Supported (All Vehicles with AP_Camera enabled)

Directionality

  • RX (Receive): The vehicle receives this command as part of a mission upload or as a direct command.

Mission Storage (AP_Mission)

  • Instance (Param 1): The target camera (1-6). 0 for "All."
  • Interval (Param 2): Time between shots in seconds.
  • Total Images (Param 3): Number of images to take. 0 for "Continuous/Unlimited."
  • Start Seq (Param 4): Sequence number for the first image (often ignored by ArduPilot storage).
  • Packing: Stored in the image_start_capture content struct.

Execution (Engineer's View)

Capture Logic

Execution is handled by AP_Camera (AP_Camera.cpp).

  1. Single vs. Multiple:
    • If Param 3 = 1, ArduPilot triggers a single take_picture() event.
    • If Param 3 > 1 or 0, it initializes a timer-based loop take_multiple_pictures().
  2. Hardware Handshake: For MAVLink-enabled cameras (e.g., Sony Airpeak or specialized gimbals), the autopilot sends the IMAGE_START_CAPTURE packet down the bus to the camera. For simple cameras, it uses the Relay/PWM shutter trigger.
  3. Termination: IMAGE_STOP_CAPTURE (2001) instantly kills any running timers and sends a "Stop" packet to MAVLink backends.
  • param1 (ID): Camera ID.
  • param2 (Interval): s.
  • param3 (Total): Count.
  • param4 (Seq): Start number.

Theory: The Data Pipeline

Still images capture significantly more detail than video frames because they use the sensor's full resolution without compression artifacts.

  • Storage Bandwidth: Capturing 42MP images every 1.5 seconds requires a high-speed UHS-II SD card. ArduPilot's mission engine handles the triggering, but the camera backend manages the actual file I/O.
  • Feedback: ArduPilot listens for CAMERA_IMAGE_CAPTURED messages from smart backends to log the precise GPS coordinate where each image was actually written to disk.

Practical Use Cases

  1. High-Res Photogrammetry:
    • Scenario: Mapping a construction site.
    • Action: IMAGE_START_CAPTURE (Interval: 2s, Total: 0). The drone flies the grid, snapping every 2 seconds until the mission ends.
  2. Point of Interest Burst:
    • Scenario: Inspecting a cracked turbine blade.
    • Action: Mission hovers at the blade. IMAGE_START_CAPTURE (Interval: 0.5s, Total: 10). The drone captures 10 high-speed shots to ensure a clear image is obtained despite vibration.

Key Parameters

Key Codebase Locations

VIDEO_START_CAPTURE (2500) / VIDEO_STOP_CAPTURE

ID: 2501

Summary

The VIDEO_START_CAPTURE and VIDEO_STOP_CAPTURE commands control the recording state of onboard video sensors. They allow a mission to automatically record only the segments of flight that are relevant to the objective, saving storage space and power.

Status

Supported (All Vehicles with AP_Camera enabled)

Directionality

  • RX (Receive): The vehicle receives this command as part of a mission upload or as a direct command.

Mission Storage (AP_Mission)

  • Stream ID (Param 1): The target video stream or camera instance.
  • Packing: Stored in the video_start_capture content struct.

Execution (Engineer's View)

Recording Logic

Execution is handled by AP_Camera::record_video (AP_Camera.cpp).

  1. Direct Control: If the camera is a simple GoPro-style camera triggered via a PWM signal, ArduPilot moves the servo/pin to the "Record" position.
  2. MAVLink Control: For high-end cameras (e.g., DJI, Sony), ArduPilot sends the standard MAVLink command to the camera's component ID.
  3. Conflict Management: If a "Start" is commanded while the camera is already recording, ArduPilot typically ignores the second command to prevent file corruption.
  • param1 (ID): Video stream/camera ID.
  • param2 (Freq): Record frequency (FPS). Typically ignored (set in camera menu).
  • param3 to param7: Unused.

Theory: Bandwidth vs. Detail

Video recording is a continuous energy drain on both the battery and the onboard processor.

  • The Overload: Modern 4K/60fps video generates significant electromagnetic interference (EMI).
  • Autonomous Recording: By using mission commands to start recording after the takeoff and stop before the landing, the pilot minimizes the noise exposure during the most critical flight phases (where GPS/Compass health is most vital).

Practical Use Cases

  1. Evidence Collection:
    • Scenario: A security drone patrolling a site.
    • Action: WAYPOINT (Start of Patrol) -> VIDEO_START_CAPTURE. The drone records the entire patrol leg and stops once it begins its return-to-launch.
  2. Cinematic Reveal:
    • Scenario: A drone flying a specific path for a film shot.
    • Action: VIDEO_START_CAPTURE is triggered precisely at the start of the camera movement.

Key Parameters

  • CAM_TYPE: Selection of camera hardware.

Key Codebase Locations