# MAVLink Camera API Discussion

**URL:** <https://discuss.px4.io/t/mavlink-camera-api-discussion/3278>\
**Category:** Uncategorized\
**Created:** [May 12, 2017, 6:36pm UTC](https://discuss.px4.io/t/mavlink-camera-api-discussion/3278 "2017-05-12T18:36:55Z")\
**Posts on this page:** 20\
**Page:** 1

<div class="post-metadata">

**Author:** ![dogmaphobic](https://discuss.px4.io/user_avatar/discuss.px4.io/dogmaphobic/32/221_2.png) [@dogmaphobic](https://discuss.px4.io/u/dogmaphobic)\
**Post date:** [May 12, 2017, 6:36pm UTC](https://discuss.px4.io/t/mavlink-camera-api-discussion/3278/1 "2017-05-12T18:36:55Z")

</div>

Following the MAVLink Camera API call conversation, I put together a draft XML camera definition file. This is by no means complete or even close to it. It’s just a starting point so we can discuss what goes in, how to format it, etc.

I put this together from the perspective of building an UI offering the user the options available to set the camera. Given the vast number of different cameras with different capabilities, I tried to keep a minimum set of options that would be common to most cameras and options that are relevant in this context. For example, I felt unnecessary to include options related to things like “Flash”, which is quite unlikely to be used. With that said, don’t take my word for it. If someone has a compelling reason to add it, we can add it.

Nothing is fixed. Not even the format. XML is easier to “read” but if the majority decides it should be Json (or something else), I’m open to anything.

The idea is to describe the camera, list the settings and the options for each setting. The GCS sends a MAVLink message requesting the camera settings and an URL is returned. That URL would point to this file. In addition to the URL, the response would also include a version for the definition file. That way, if the GCS already has it cached, it won’t need to download it again. The GCS can then build the UI on the fly based on the information contained within the definition file.

Options have an “index” (the numerical value used in their respective MAVLink command) and the text used to fill the UI elements. A setting may also have a “Title” to be used in the UI. There can be one or more “settings” element in order to deal with localization. Each element defines a set of settings for a given locale. If a desired language is not found, the default is used.

Most things are optional. For example, if the camera has no setting for “Aspect Ratio”, the element is simply not included. The options within a setting are completely up to the camera. The GCS will simply present the list and use the “index" when setting the values in the MAVLink command.

Note that all settings in the final list will need a counterpart MAVLink command. See [CAMERA\_SETTINGS](http://mavlink.org/messages/common/#MAV_CMD_SET_CAMERA_SETTINGS_1) for what is there now.

We need to sort out how to define exclusion rules. For instance, when you set the camera’s exposure mode to “Auto”, usually you don’t change ISO, Shutter Speed or Aperture. That’s what’s “Auto” is for. However, you are allowed to change “Exposure Compensation” (EV Value). When in “Manual” mode, the opposite is true.

I’ve added “Metering Mode” as this is common in most cameras. I’m not sure about the value of it though. This could be a case like “Flash” options described above. It may not apply in this context. Anything other than “Average” would require further settings, which can easily turn this into an unmanageable nightmare. I’m open to opinions.

```
<camera>
    <description>
        <infoVersion>1</infoVersion>
        <cameraModel>Super Duper SDII</cameraModel>
        <manufacturerName>Super Duper Inc.</manufacturerName>
        <minFocalLength>12</minFocalLength>
        <maxFocalLength>12</maxFocalLength>
        <sensorWidthPixels>4000</sensorWidthPixels>
        <sensorHeightPixels>3000</sensorHeightPixels>
        <sensorWidth>12.4</sensorWidth>
        <sensorHeight>9.3</sensorHeight>
        <hasVideoStream>1</hasVideoStream>
    </description>
    <settings locale="en_US" default="1">
        <mode title="Camera Mode" command="530" parameter="2">
            <value index="0">Still</value>
            <value index="1">Movie</value>
        </mode>
        <videoStream>
            <size title="Stream Resolution" command="???" parameter="???">
                <value index="0">480P</value>
                <value index="1">720P</value>
                <value index="2">1080P</value>
            </size>
        </videoStream>
        <exposure>
            <mode title="Exposure Mode" command="523" parameter="5">
                <value index="0">Program Auto</value>
                <value index="1">Auto</value>
                <value index="2">Shutter Priority</value>
                <value index="3">Aperture Priority</value>
                <value index="4">Manual</value>
            </mode>
            <aperture title="Aperture" command="523" parameter="2">
                <value index="0">1.4</value>
                <value index="1">1.8</value>
                <value index="2">2.0</value>
                <value index="3">2.2</value>
                <value index="4">2.4</value>
            </aperture>
            <shutter title="Shutter Speed" command="523" parameter="3">
                <value index="0">1s</value>
                <value index="1">1/8</value>
                <value index="2">1/15</value>
                <value index="3">1/30</value>
                <value index="4">1/60</value>
                <value index="5">1/125</value>
                <value index="6">1/250</value>
                <value index="7">1/500</value>
                <value index="8">1/1000</value>
            </shutter>
            <iso title="ISO" command="523" parameter="4">
                <value index="0">100</value>
                <value index="1">200</value>
                <value index="2">400</value>
                <value index="3">800</value>
                <value index="4">1600</value>
                <value index="5">3200</value>
            </iso>
            <ev tile="Exposure Compensation" command="523" parameter="6">
                <value index="0">-2.0</value>
                <value index="1">-1.5</value>
                <value index="2">-1.0</value>
                <value index="3">-0.5</value>
                <value index="4">0</value>
                <value index="5">+0.5</value>
                <value index="6">+1.0</value>
                <value index="7">+1.5</value>
                <value index="8">+2.0</value>
            </ev>
            <metering title="Metering Mode" command="524" parameter="3">
                <value index="0">Average</value>
                <value index="1">Center</value>
                <value index="2">Spot</value>
            </metering>
        </exposure>
        <color title="Color Mode" command="524" parameter="6">
            <value index="0">Neutral</value>
            <value index="1">Vivid</value>
            <value index="2">Black and White</value>
        </color>
        <stabilization title="Image Stabilization" command="???" parameter="???">
            <value index="0">Off</value>
            <value index="1">On</value>
        </stabilization>
        <whiteBalance title="White Balance" command="523" parameter="7">
            <value index="0">Auto</value>
            <value index="1">Daylight</value>
            <value index="2">Shade</value>
            <value index="3">Cloudy</value>
            <value index="4">Incandescent</value>
            <value index="5">Fluorescent</value>
        </whiteBalance>
        <still>
            <aspectRatio title="Aspect Ratio" command="???" parameter="???">
                <value index="0">16:9</value>
                <value index="1">4:3</value>
                <value index="2">3:2</value>
                <value index="3">1:1</value>
            </aspectRatio>
            <format title="Image Format" command="524" parameter="4">
                <value index="0">JPEG</value>
                <value index="1">RAW</value>
                <value index="2">RAW + JPEG</value>
            </format>
        </still>
        <movie>
            <format title="Movie Format" command="???" parameter="???">
                <value index="0">MP4</value>
                <value index="1">MOV</value>
                <value index="2">MPEG</value>
            </format>
            <size title="Movie Resolution" command="???" parameter="???">
                <value index="0">3840x2160 30p</value>
                <value index="1">3840x2160 24p</value>
                <value index="2">1920x1080 60p</value>
                <value index="3">1920x1080 30p</value>
                <value index="4">1920x1080 24p</value>
            </size>
            <audio title="Audio Recording" command="530" parameter="3">
                <value index="0">Off</value>
                <value index="1">On</value>
            </audio>
        </movie>
    </settings>
</camera>
```

---

<div class="post-metadata">

**Author:** ![dogmaphobic](https://discuss.px4.io/user_avatar/discuss.px4.io/dogmaphobic/32/221_2.png) [@dogmaphobic](https://discuss.px4.io/u/dogmaphobic)\
**Post date:** [May 12, 2017, 6:44pm UTC](https://discuss.px4.io/t/mavlink-camera-api-discussion/3278/2 "2017-05-12T18:44:00Z")

</div>

No matter how many times I went over this, every time I read it I find new things that I’ve missed. For instance, there should be a correlation between a setting and a MAVLink command. Otherwise you won’t know which command to use.

I’ve edited it to include the MAVLink command and parameter used to each setting. Those that don’t have one, I used “???”.

---

<div class="post-metadata">

**Author:** ![JulianOes](https://discuss.px4.io/user_avatar/discuss.px4.io/julianoes/32/30_2.png) [@JulianOes](https://discuss.px4.io/u/JulianOes)\
**Post date:** [May 15, 2017, 1:01pm UTC](https://discuss.px4.io/t/mavlink-camera-api-discussion/3278/3 "2017-05-15T13:01:39Z")

</div>

> [@dogmaphobic](#):
>
> \<metering title=“Metering Mode” command=“524” parameter=“3”\>  
> \<value index=“0”\>Average\</value\>  
> \<value index=“1”\>Center\</value\>  
> \<value index=“2”\>Spot\</value\>  
> \</metering\>

I’m not sure how a machine would parse this. I would rather say that the modes are “hard-coded” given in the mavlink specs (and they can always get extended). and the xml only specifies which ones are supported by the camera.

Therefore the xml would only say:

```auto
<setting name="metering_mode" description="only average and center supported by super duper camera">
<value>0</value>
<value>1</value>
</setting>

```

So, basically, you don’t describe settings but rather whitelist possible options.

And for settings that include numbers (not IDs) such as resolution, aperture, etc. you can specifiy the possible numbers.

---

<div class="post-metadata">

**Author:** ![dogmaphobic](https://discuss.px4.io/user_avatar/discuss.px4.io/dogmaphobic/32/221_2.png) [@dogmaphobic](https://discuss.px4.io/u/dogmaphobic)\
**Post date:** [May 15, 2017, 10:43pm UTC](https://discuss.px4.io/t/mavlink-camera-api-discussion/3278/4 "2017-05-15T22:43:58Z")

</div>

This is meant to provide the data necessary to build the user interface to show the user. It’s meant to be read by humans and not machines. How do you populate a “Metering Mode” drop down box? With “0” and “1”? And the title would be “metering\_mode”? With a description that is only relevant to a developer?

Am I missing something?

---

<div class="post-metadata">

**Author:** ![JulianOes](https://discuss.px4.io/user_avatar/discuss.px4.io/julianoes/32/30_2.png) [@JulianOes](https://discuss.px4.io/u/JulianOes)\
**Post date:** [May 16, 2017, 2:21pm UTC](https://discuss.px4.io/t/mavlink-camera-api-discussion/3278/5 "2017-05-16T14:21:54Z")

</div>

Ok, makes sense for “custom defined enums” such as metering mode.

However, I don’t see why you would add indices to the different ISO values, when the values themselves are already unique numbers.

---

<div class="post-metadata">

**Author:** ![dogmaphobic](https://discuss.px4.io/user_avatar/discuss.px4.io/dogmaphobic/32/221_2.png) [@dogmaphobic](https://discuss.px4.io/u/dogmaphobic)\
**Post date:** [May 16, 2017, 2:25pm UTC](https://discuss.px4.io/t/mavlink-camera-api-discussion/3278/6 "2017-05-16T14:25:50Z")

</div>

> [@JulianOes](#):
>
> I don’t see why you would add indices to the different ISO values, when the values themselves are already unique numbers.

You don’t know that. This is to maintain consistency for all settings. The UI uses the “value” as a display name and the “index” as an argument to the parameter. Who knows, maybe someone will have only “High ISO” and “Low ISO” (with index 0 and 1).

---

<div class="post-metadata">

**Author:** ![JulianOes](https://discuss.px4.io/user_avatar/discuss.px4.io/julianoes/32/30_2.png) [@JulianOes](https://discuss.px4.io/u/JulianOes)\
**Post date:** [May 16, 2017, 2:29pm UTC](https://discuss.px4.io/t/mavlink-camera-api-discussion/3278/7 "2017-05-16T14:29:23Z")

</div>

Got it, thanks for the explanation.

---

<div class="post-metadata">

**Author:** ![dogmaphobic](https://discuss.px4.io/user_avatar/discuss.px4.io/dogmaphobic/32/221_2.png) [@dogmaphobic](https://discuss.px4.io/u/dogmaphobic)\
**Post date:** [May 17, 2017, 1:04am UTC](https://discuss.px4.io/t/mavlink-camera-api-discussion/3278/8 "2017-05-17T01:04:25Z")

</div>

For completeness’ sake, here are the commands related to cameras currently defined. The XML file above was mostly based on these commands.

```
521 MAV_CMD_REQUEST_CAMERA_INFORMATION WIP: Request camera information (CAMERA_INFORMATION)
Mission Param #1 Camera ID (0 for all cameras, 1 for first, 2 for second, etc.)
Mission Param #2 0: No action 1: Request camera capabilities
Mission Param #3 Reserved (all remaining params)

522 MAV_CMD_REQUEST_CAMERA_SETTINGS WIP: Request camera settings (CAMERA_SETTINGS)
Mission Param #1 Camera ID (0 for all cameras, 1 for first, 2 for second, etc.)
Mission Param #2 0: No Action 1: Request camera settings
Mission Param #3 Reserved (all remaining params)

523 MAV_CMD_SET_CAMERA_SETTINGS_1 WIP: Set the camera settings part 1 (CAMERA_SETTINGS). Use NAN for values you don't want to change.
Mission Param #1 Camera ID (1 for first, 2 for second, etc.)
Mission Param #2 Aperture (1/value)
Mission Param #3 Shutter speed in seconds
Mission Param #4 ISO sensitivity
Mission Param #5 AE mode (Auto Exposure) (0: full auto 1: full manual 2: aperture priority 3: shutter priority)
Mission Param #6 EV value (when in auto exposure)
Mission Param #7 White balance (color temperature in K) (0: Auto WB)

524 MAV_CMD_SET_CAMERA_SETTINGS_2 WIP: Set the camera settings part 2 (CAMERA_SETTINGS). Use NAN for values you don't want to change.
Mission Param #1 Camera ID (1 for first, 2 for second, etc.)
Mission Param #2 Reserved for Flicker mode (0 for Auto)
Mission Param #3 Reserved for metering mode ID (Average, Center, Spot, etc.)
Mission Param #4 Reserved for image format ID (Jpeg/Raw/Jpeg+Raw)
Mission Param #5 Reserved for image quality ID (Compression)
Mission Param #6 Reserved for color mode ID (Neutral, Vivid, etc.)
Mission Param #7 Reserved

525 MAV_CMD_REQUEST_STORAGE_INFORMATION WIP: Request storage information (STORAGE_INFORMATION)
Mission Param #1 Storage ID (0 for all, 1 for first, 2 for second, etc.)
Mission Param #2 0: No Action 1: Request storage information
Mission Param #3 Reserved (all remaining params)

526 MAV_CMD_STORAGE_FORMAT WIP: Format a storage medium
Mission Param #1 Storage ID (1 for first, 2 for second, etc.)
Mission Param #2 0: No action 1: Format storage
Mission Param #3 Reserved (all remaining params)

527 MAV_CMD_REQUEST_CAMERA_CAPTURE_STATUS WIP: Request camera capture status (CAMERA_CAPTURE_STATUS)
Mission Param #1 Camera ID (0 for all cameras, 1 for first, 2 for second, etc.)
Mission Param #2 0: No Action 1: Request camera capture status
Mission Param #3 Reserved (all remaining params)

528 MAV_CMD_REQUEST_FLIGHT_INFORMATION WIP: Request flight information (FLIGHT_INFORMATION)
Mission Param #1 1: Request flight information
Mission Param #2 Reserved (all remaining params)

529 MAV_CMD_RESET_CAMERA_SETTINGS WIP: Reset all camera settings to Factory Default (CAMERA_SETTINGS)
Mission Param #1 Camera ID (0 for all cameras, 1 for first, 2 for second, etc.)
Mission Param #2 0: No Action 1: Reset all settings
Mission Param #3 Reserved (all remaining params)

530 MAV_CMD_SET_CAMERA_MODE WIP: Set camera running mode. Use NAN for values you don't want to change.
Mission Param #1 Camera ID (0 for all cameras, 1 for first, 2 for second, etc.)
Mission Param #2 Camera mode (0: photo mode, 1: video mode)
Mission Param #3 Audio recording enabled (0: off 1: on)
Mission Param #4 Reserved (all remaining params)

2000 MAV_CMD_IMAGE_START_CAPTURE WIP: Start image capture sequence. Sends CAMERA_IMAGE_CAPTURED after each capture.
Mission Param #1 Camera ID (0 for all cameras, 1 for first, 2 for second, etc.)
Mission Param #2 Duration between two consecutive pictures (in seconds)
Mission Param #3 Number of images to capture total - 0 for unlimited capture
Mission Param #4 Resolution horizontal in pixels (set to -1 for highest resolution possible)
Mission Param #5 Resolution vertical in pixels (set to -1 for highest resolution possible)

2001 MAV_CMD_IMAGE_STOP_CAPTURE WIP: Stop image capture sequence
Mission Param #1 Camera ID (0 for all cameras, 1 for first, 2 for second, etc.)
Mission Param #2 Reserved

2002 MAV_CMD_REQUEST_CAMERA_IMAGE_CAPTURE WIP: Re-request a CAMERA_IMAGE_CAPTURE packet
Mission Param #1 Camera ID (0 for all cameras, 1 for first, 2 for second, etc.)
Mission Param #2 Sequence number for missing CAMERA_IMAGE_CAPTURE packet
Mission Param #3 Reserved (all remaining params)

2003 MAV_CMD_DO_TRIGGER_CONTROL Enable or disable on-board camera triggering system.
Mission Param #1 Trigger enable/disable (0 for disable, 1 for start), -1 to ignore
Mission Param #2 1 to reset the trigger sequence, -1 or 0 to ignore
Mission Param #3 1 to pause triggering, but without switching the camera off or retracting it. -1 to ignore

2500 MAV_CMD_VIDEO_START_CAPTURE WIP: Starts video capture (recording)
Mission Param #1 Camera ID (0 for all cameras, 1 for first, 2 for second, etc.)
Mission Param #2 Frames per second, set to -1 for highest framerate possible.
Mission Param #3 Resolution horizontal in pixels (set to -1 for highest resolution possible)
Mission Param #4 Resolution vertical in pixels (set to -1 for highest resolution possible)
Mission Param #5 Frequency CAMERA_CAPTURE_STATUS messages should be sent while recording (0 for no messages, otherwise time in Hz)

2501 MAV_CMD_VIDEO_STOP_CAPTURE WIP: Stop the current video capture (recording)
Mission Param #1 Camera ID (0 for all cameras, 1 for first, 2 for second, etc.)
Mission Param #2 Reserved

2502 MAV_CMD_VIDEO_START_STREAMING WIP: Start video streaming
Mission Param #1 Camera ID (0 for all cameras, 1 for first, 2 for second, etc.)
Mission Param #2 Reserved

2503 MAV_CMD_VIDEO_STOP_STREAMING WIP: Stop the current video streaming
Mission Param #1 Camera ID (0 for all cameras, 1 for first, 2 for second, etc.)
Mission Param #2 Reserved

2504 MAV_CMD_REQUEST_VIDEO_STREAM_INFORMATION WIP: Request video stream information (VIDEO_STREAM_INFORMATION)
Mission Param #1 Camera ID (0 for all cameras, 1 for first, 2 for second, etc.)
Mission Param #2 0: No Action 1: Request video stream information
Mission Param #3 Reserved (all remaining params)
```

---

<div class="post-metadata">

**Author:** ![dogmaphobic](https://discuss.px4.io/user_avatar/discuss.px4.io/dogmaphobic/32/221_2.png) [@dogmaphobic](https://discuss.px4.io/u/dogmaphobic)\
**Post date:** [May 17, 2017, 1:06am UTC](https://discuss.px4.io/t/mavlink-camera-api-discussion/3278/9 "2017-05-17T01:06:03Z")

</div>

And these are the messages:

```
CAMERA_INFORMATION ( #259 )
WIP: Information about a camera

Field Name Type Description
time_boot_ms uint32_t Timestamp (milliseconds since system boot)
camera_id uint8_t Camera ID (1 for first, 2 for second, etc.)
camera_count uint8_t Number of cameras
vendor_name uint8_t[32] Name of the camera vendor
model_name uint8_t[32] Name of the camera model
firmware_version uint32_t Version of the camera firmware
focal_length float Focal length in mm
sensor_size_h float Image sensor size horizontal in mm
sensor_size_v float Image sensor size vertical in mm
resolution_h uint16_t Image resolution in pixels horizontal
resolution_v uint16_t Image resolution in pixels vertical
lens_id uint8_t Reserved for a lens ID

CAMERA_SETTINGS ( #260 )
WIP: Settings of a camera, can be requested using MAV_CMD_REQUEST_CAMERA_SETTINGS and written using MAV_CMD_SET_CAMERA_SETTINGS

Field Name Type Description
time_boot_ms uint32_t Timestamp (milliseconds since system boot)
camera_id uint8_t Camera ID (1 for first, 2 for second, etc.)
exposure_mode uint8_t 0: full auto 1: full manual 2: aperture priority 3: shutter priority
aperture float Aperture is 1/value
shutter_speed float Shutter speed in seconds
iso_sensitivity float ISO sensitivity
ev float Exposure Value
white_balance float Color temperature in degrees Kelvin. (0: Auto WB)
mode_id uint8_t Reserved for a camera mode ID. (0: Photo 1: Video)
audio_recording uint8_t Audio recording enabled (0: off 1: on)
color_mode_id uint8_t Reserved for a color mode ID (Neutral, Vivid, etc.)
image_format_id uint8_t Reserved for image format ID (Jpeg/Raw/Jpeg+Raw)
image_quality_id uint8_t Reserved for image quality ID (Compression)
metering_mode_id uint8_t Reserved for metering mode ID (Average, Center, Spot, etc.)
flicker_mode_id uint8_t Reserved for flicker mode ID (Auto, 60Hz, 50Hz, etc.)

STORAGE_INFORMATION ( #261 )
WIP: Information about a storage medium

Field Name Type Description
time_boot_ms uint32_t Timestamp (milliseconds since system boot)
storage_id uint8_t Storage ID (1 for first, 2 for second, etc.)
storage_count uint8_t Number of storage devices
status uint8_t Status of storage (0 not available, 1 unformatted, 2 formatted)
total_capacity float Total capacity in MiB
used_capacity float Used capacity in MiB
available_capacity float Available capacity in MiB
read_speed float Read speed in MiB/s
write_speed float Write speed in MiB/s

CAMERA_CAPTURE_STATUS ( #262 )
WIP: Information about the status of a capture

Field Name Type Description
time_boot_ms uint32_t Timestamp (milliseconds since system boot)
camera_id uint8_t Camera ID (1 for first, 2 for second, etc.)
image_status uint8_t Current status of image capturing (0: not running, 1: interval capture in progress)
video_status uint8_t Current status of video capturing (0: not running, 1: capture in progress)
image_interval float Image capture interval in seconds
video_framerate float Video frame rate in Hz
image_resolution_h uint16_t Image resolution in pixels horizontal
image_resolution_v uint16_t Image resolution in pixels vertical
video_resolution_h uint16_t Video resolution in pixels horizontal
video_resolution_v uint16_t Video resolution in pixels vertical
recording_time_ms uint32_t Time in milliseconds since recording started
available_capacity float Available storage capacity in MiB

CAMERA_IMAGE_CAPTURED ( #263 )
WIP: Information about a captured image

Field Name Type Description
time_boot_ms uint32_t Timestamp (milliseconds since system boot)
time_utc uint64_t Timestamp (microseconds since UNIX epoch) in UTC. 0 for unknown.
camera_id uint8_t Camera ID (1 for first, 2 for second, etc.)
lat int32_t Latitude, expressed as degrees * 1E7 where image was taken
lon int32_t Longitude, expressed as degrees * 1E7 where capture was taken
alt int32_t Altitude in meters, expressed as * 1E3 (AMSL, not WGS84) where image was taken
relative_alt int32_t Altitude above ground in meters, expressed as * 1E3 where image was taken
q float[4] Quaternion of camera orientation (w, x, y, z order, zero-rotation is 0, 0, 0, 0)
image_index int32_t Zero based index of this image (image count since armed -1)
capture_result int8_t Boolean indicating success (1) or failure (0) while capturing this image.
file_url char[205] URL of image taken. Either local storage or http://foo.jpg if camera provides an HTTP interface.

VIDEO_STREAM_INFORMATION ( #269 )
WIP: Information about video stream

Field Name Type Description
camera_id uint8_t Camera ID (1 for first, 2 for second, etc.)
status uint8_t Current status of video streaming (0: not running, 1: in progress)
framerate float Frames per second
resolution_h uint16_t Resolution horizontal in pixels
resolution_v uint16_t Resolution vertical in pixels
bitrate uint32_t Bit rate in bits per second
rotation uint16_t Video image rotation clockwise
uri char[230] Video stream URI

SET_VIDEO_STREAM_SETTINGS ( #270 )
WIP: Message that sets video stream settings

Field Name Type Description
target_system uint8_t system ID of the target
target_component uint8_t component ID of the target
camera_id uint8_t Camera ID (1 for first, 2 for second, etc.)
framerate float Frames per second (set to -1 for highest framerate possible)
resolution_h uint16_t Resolution horizontal in pixels (set to -1 for highest resolution possible)
resolution_v uint16_t Resolution vertical in pixels (set to -1 for highest resolution possible)
bitrate uint32_t Bit rate in bits per second (set to -1 for auto)
rotation uint16_t Video image rotation clockwise (0-359 degrees)
uri char[230] Video stream URI
```

---

<div class="post-metadata">

**Author:** ![dogmaphobic](https://discuss.px4.io/user_avatar/discuss.px4.io/dogmaphobic/32/221_2.png) [@dogmaphobic](https://discuss.px4.io/u/dogmaphobic)\
**Post date:** [May 17, 2017, 5:27pm UTC](https://discuss.px4.io/t/mavlink-camera-api-discussion/3278/10 "2017-05-17T17:27:32Z")

</div>

To clarify, for each setting described in the XML file, we need a way to _ **SET** _ the option value and a way to _ **GET** _ the current setting. I listed within the settings the existing (or non existing) command used to set the option. What I have not done is to describe how to get the current value for a given setting. That’s a big whole in the spec. We need a way to describe within the XML file how to get the current value. I’m not sure how to make it fit the current message definitions. It almost feels like we need a simpler set of arbitrary Get/Set commands (as opposed to a hardcoded structure as it is currently the case). To use the existing structure as is, we would need to specify which command to use to get the settings, which message contains the response, which field in the message and its type. Quite a lot. I’m open to suggestions.

---

<div class="post-metadata">

**Author:** ![mcharleb](https://discuss.px4.io/letter_avatar_proxy/v4/letter/m/50afbb/32.png) [@mcharleb](https://discuss.px4.io/u/mcharleb)\
**Post date:** [May 17, 2017, 7:23pm UTC](https://discuss.px4.io/t/mavlink-camera-api-discussion/3278/11 "2017-05-17T19:23:51Z")

</div>

One option would be to get the struct of information, modify what you want to set, and send back the struct.

---

<div class="post-metadata">

**Author:** ![otaviobp](https://discuss.px4.io/letter_avatar_proxy/v4/letter/o/f04885/32.png) [@otaviobp](https://discuss.px4.io/u/otaviobp)\
**Post date:** [May 23, 2017, 3:09am UTC](https://discuss.px4.io/t/mavlink-camera-api-discussion/3278/12 "2017-05-23T03:09:25Z")

</div>

> [@dogmaphobic](#):
>
> To clarify, for each setting described in the XML file, we need a way to SET the option value and a way to GET the current setting

I didn’t get one point. Are you saying that we will need a way to GET and SET the values using MAVLink? Are you proposing a message like VIDEO\_SETTINGS\_GET\_VALUE and VIDEO\_SETTINGS\_SET\_VALUE (or something similar) or having multiple MAVLink messages to get/set each value?

---

<div class="post-metadata">

**Author:** ![otaviobp](https://discuss.px4.io/letter_avatar_proxy/v4/letter/o/f04885/32.png) [@otaviobp](https://discuss.px4.io/u/otaviobp)\
**Post date:** [May 23, 2017, 3:22am UTC](https://discuss.px4.io/t/mavlink-camera-api-discussion/3278/13 "2017-05-23T03:22:59Z")

</div>

I would prefer to have one generic get/set message so a camera could have custom fields. I don’t think we need to limit the possibilities of options/values in the mavlink messages as we are currently doing.  
As far as I understand we could have a XML like:

```
[...] 
<videoStream>
            <custom_field title="Custom">
                <value index="0">custom_field0</value>
                <value index="1">custom_field1</value>
            </custom>
</videoStream>
[...]

```

and we could use the message SET\_VIDEO\_SETTINGS(…, “custom\_field”, 0) to set the value of that custom field. Is that your proposal?

And if so, why would we need the command and parameter fields? Are they just to be used with commands that are specific?

---

<div class="post-metadata">

**Author:** ![alexey](https://discuss.px4.io/letter_avatar_proxy/v4/letter/a/47e85d/32.png) [@alexey](https://discuss.px4.io/u/alexey)\
**Post date:** [May 23, 2017, 2:29pm UTC](https://discuss.px4.io/t/mavlink-camera-api-discussion/3278/14 "2017-05-23T14:29:50Z")

</div>

So it will be two ways for get/set parameters of camera:

1. Add special commands for every parameter MAV\_CMD\_[PARAMETER\_NAME]_SET and MAV\_CMD_[PARAMETER\_NAME]\_GET. But it will leads to a huge number of commands and also it complicates adding new params.
2. Add universal messages SET\_CAMERA\_PARAMETER and GET\_CAMERA\_PARAMETER with (for example) the following fields: camera\_id, section\_name (video, still, etc.), field\_name, value(index). This way seems is more preferable.  
But there are some questions:
3. What to do with old messages for getting/setting params?
4. If old messages will be deprecated and also there are some parameters which doesn’t have list of available values, for example URI of video streaming and we can’t use new messages for them. How their values will be get/set then?
5. How to get file using serial connection?

---

<div class="post-metadata">

**Author:** ![dogmaphobic](https://discuss.px4.io/user_avatar/discuss.px4.io/dogmaphobic/32/221_2.png) [@dogmaphobic](https://discuss.px4.io/u/dogmaphobic)\
**Post date:** [May 23, 2017, 4:52pm UTC](https://discuss.px4.io/t/mavlink-camera-api-discussion/3278/15 "2017-05-23T16:52:33Z")

</div>

As I said, the proposed draft above is a starting point so we can, as group, discuss and come up with something that makes sense. For the most part, I put together the XML file based on the existing MAVLink messages. These would form the _core_ functions and options.

> Are you saying that we will need a way to GET and SET the values using MAVLink? Are you proposing a message like VIDEO\_SETTINGS\_GET\_VALUE and VIDEO\_SETTINGS\_SET\_VALUE (or something similar)

We need a core set of functions. Basically what has already been added to MAVLink with maybe some tweaks (I think even what has already been added to be too much specialization.) These would satisfy the basics needs without requiring either vehicle to provide nor GCS to download and parse the XML file above. In summary, how things are done today.

For more specialized use however, it’s impractical to think we will have an infinite number of MAVLink commands and messages to satisfy them all. That’s where I think a pair of arbitrary command/message would come in play. A command where the arguments are arbitrary, and a corresponding response (if needed). That way, we can do anything with just one pair of command/response. But for that to work, we need something that defines what these arbitrary commands and response fields are.

> I would prefer to have one generic get/set message so a camera could have custom fields. I don’t think we need to limit the possibilities of options/values in the mavlink messages as we are currently doing.

This is exactly what I had in mind but we can’t drop the common core messages for when you don’t have the resources to deal with the XML definition file.

> What to do with old messages for getting/setting params?

As I explained above, they stay. We may fine tune them but we can’t realistically require every system to provide and/or parse the definition file.

> If old messages will be deprecated and also there are some parameters which doesn’t have list of available

I don’t think old messages should be deprecated as I explained above. You should always have some core functionality that is standard and understood by all.

> How to get file using serial connection?

Normally you don’t. If you have limited capabilities, you would be limited to the core messages. The idea is that the GCS, while connected to the vehicle and Internet would download the definition file (if it exists). Once downloaded, you have the information and until some upgrade is done, you won’t have to download it again.

---

<div class="post-metadata">

**Author:** ![lbegani](https://discuss.px4.io/letter_avatar_proxy/v4/letter/l/f6c823/32.png) [@lbegani](https://discuss.px4.io/u/lbegani)\
**Post date:** [May 26, 2017, 8:57am UTC](https://discuss.px4.io/t/mavlink-camera-api-discussion/3278/16 "2017-05-26T08:57:52Z")

</div>

I am currently going through the camera mavlink messages and the camera definition file proposed to do a holistic review of camera usecases like image capture, video capture, video streaming, video snapshot etc and related parameters, protocols, formats etc. Idea is to improve the camera experience with drones. Before I put together my findings, I wanted to know if this forum is the right place for such discussion, kindly advice.

> [@dogmaphobic](#):
>
> Given the vast number of different cameras with different capabilities, I tried to keep a minimum set of options that would be common to most cameras and options that are relevant in this context

I have a different take on this. Given that drones would be installed with most high-end and powerful cameras, I think the list of setting options available to the user to control the camera needs to be as exhaustive as possible.

---

<div class="post-metadata">

**Author:** ![dogmaphobic](https://discuss.px4.io/user_avatar/discuss.px4.io/dogmaphobic/32/221_2.png) [@dogmaphobic](https://discuss.px4.io/u/dogmaphobic)\
**Post date:** [May 26, 2017, 3:45pm UTC](https://discuss.px4.io/t/mavlink-camera-api-discussion/3278/17 "2017-05-26T15:45:54Z")

</div>

This is an evolving discussion. Did you read my comments right above your post?

> I think the list of setting options available to the user to control the camera needs to be as exhaustive as possible.

I don’t disagree, the issue is that most settings have random options depending on the camera. A given camera may have an ISO range from 50 to 25000 while another may be _Low_, _Medium_ and _High_. The issue becomes how to let the GCS know what these options are so it can present them to the user in the UI. What if a camera doesn’t have any ISO setting at all? That’s why we need some form of _Camera Definition_ to help the GCS know what to present to the user.

Then the issue of future proofing it. No matter how exhaustive the initial set of messages is, there could be a new camera tomorrow that say, can switch from visible light to thermal imaging. If that was not part of the protocol, there won’t be a way to set it unless a new message is added. That’s why I think it makes more sense to have just a simple set of Get/Set messages with a Key/Value pair. That would allow you to set anything.

---

<div class="post-metadata">

**Author:** ![DonLakeFlyer](https://discuss.px4.io/user_avatar/discuss.px4.io/donlakeflyer/32/3036_2.png) [@DonLakeFlyer](https://discuss.px4.io/u/DonLakeFlyer)\
**Post date:** [May 26, 2017, 5:13pm UTC](https://discuss.px4.io/t/mavlink-camera-api-discussion/3278/18 "2017-05-26T17:13:22Z")

</div>

I would say that was Gus has described makes a ton of sense.

---

<div class="post-metadata">

**Author:** ![lbegani](https://discuss.px4.io/letter_avatar_proxy/v4/letter/l/f6c823/32.png) [@lbegani](https://discuss.px4.io/u/lbegani)\
**Post date:** [May 29, 2017, 4:27am UTC](https://discuss.px4.io/t/mavlink-camera-api-discussion/3278/19 "2017-05-29T04:27:41Z")

</div>

What I understand from the discussion is -

1. MAVLink protocol will only define a template for camera definition file and not the parameters.
2. Vehicle with camera will need to fill in the user-defined params as k-v pairs and host the file for download.
3. GCS will download the file and build the UI based on parameters.
4. GCS will send set/get messages for each parameter to configure the camera.  
Is my understanding correct? Suppose if there are 50 params, will there be an exchange of 50 get/set messages?

---

<div class="post-metadata">

**Author:** ![dogmaphobic](https://discuss.px4.io/user_avatar/discuss.px4.io/dogmaphobic/32/221_2.png) [@dogmaphobic](https://discuss.px4.io/u/dogmaphobic)\
**Post date:** [May 29, 2017, 4:15pm UTC](https://discuss.px4.io/t/mavlink-camera-api-discussion/3278/20 "2017-05-29T16:15:08Z")

</div>

> [@lbegani](#):
>
> 1. MAVLink protocol will only define a template for camera definition file and not the parameters.

No, it will have a basic set of messages, enough to handle a basic camera with known parameters. The definition file is to be able to extend camera functionality beyond the basics.

> 1. Vehicle with camera will need to fill in the user-defined params as k-v pairs and host the file for download.

The vehicle does not need to host the file (though it could if it can). The idea is to have the file hosted somewhere on the Internet. You don’t _fill in_ the parameters. These are set once by the camera manufacturer/integrator and saved into the XML file.

> 1. GCS will download the file and build the UI based on parameters.

Correct. If there is no definition file, only the basic set of options are available.

> 1. GCS will send set/get messages for each parameter to configure the camera.  
> Is my understanding correct? Suppose if there are 50 params, will there be an exchange of 50 get/set messages?

As it current stands, yes. If you have a better idea, this is why this discussion was started. To come up with ways to deal with this. Yes, if you could send a whole json file or POST a request with all the get/set at once it would be better but that’s not how MAVLink works.

[Next page](https://discuss.px4.io/t/mavlink-camera-api-discussion/3278.md?page=2)