Camera API subedit #163

hamishwillee · 2019-01-13T07:09:27Z

@dogmaphobic This subedits the API following #162. Unfortunately I did some irrelevant tidying at the same time and covered the whole API, so hard to see wood from trees. I'll add notes inline for bits that need checking

You can see the rendered version of this here: https://hamishwillee.gitbooks.io/ham_mavdevguide/content/v/cameraupdates/en/services/camera.html#camera-identification

I quite like sequence diagrams as a test of the logic. Might add them more generally in future.

hamishwillee · 2019-01-13T07:12:26Z

en/services/camera.md


-> **Note** If no response is sent for a `MAV_CMD_REQUEST_CAMERA_INFORMATION` message, it is assumed camera support is not available and no support for it will be provided by the GCS.
+{% mermaid %}


YOu can see the rendered version of this here.

Docs seem to indicate:

CAMERA_INFORMATION not received back means that camera API not supported.

MAV_CMD_REQUEST_CAMERA_INFORMATION is not resent - if message lost, then it's gone and we just assume camera API not supported

This is only sent for first heartbeat from camera component.
Is that correct? What is the timeout (or is there one).

As an aside, I like these diagrams. They give a good opportunity to question whether flow is correctly documented.

I have to go back and double check. The idea is that if the message (MAV_CMD_REQUEST_CAMERA_INFORMATION) is ACK'ed, QGC will keep asking until it receives the CAMERA_INFORMATION message. This is how the video streaming protocol works (it's fresh in my head).

As an aside, I like these diagrams. They give a good opportunity to question whether flow is correctly documented.

Yes, I thought about it while I was adding the video stuff but I didn't know how to add one.

In summary:

GCS sends MAV_CMD_REQUEST_CAMERA_INFORMATION after heartbeat.
Standard protocol will retry the command 3 times if it gets no response (ACK or NAK).
If ACK is received, it will wait for the CAMERA_INFORMATION message. If it doesn't get it, it will keep trying (also 3 times). Note that if the count field is more than one, the GCS will wait for that count of messages, one for each camera.

The same applies to video info.

Regarding diagrams, if you don't want to set up the build environment and just rely on a text editor, the easiest way to render them is to use https://mermaidjs.github.io/mermaid-live-editor/. Basically you open that URL, copy and existing diagram like the one below, omitting the open and close "mermaid tags" and past into the block labeled code on the side. Edit the sequence info (pretty easy) and then copy past back into your doc with mermaid tags.

{% mermaid %} sequenceDiagram; participant GCS participant Camera Camera->>GCS: HEARTBEAT [cmp id: MAV_COMP_ID_CAMERA] (first) GCS->>Camera: MAV_CMD_REQUEST_CAMERA_INFORMATION GCS->>GCS: Start timeout Camera->>GCS: CAMERA_INFORMATION {% endmermaid %}

GCS sends MAV_CMD_REQUEST_CAMERA_INFORMATION after heartbeat.

Yes, but which heartbeat - just the first one? Or to put it another way I assume that this whole process only happens on first connection to a camera component. After we've got CAMERA_INFORMATION don't try get it again when the next HEARTBEAT arrives?

@dogmaphobic OK, I have re-written this section to capture your point about resends and acks. This should be good to review.

hamishwillee · 2019-01-13T07:14:32Z

en/services/camera.md

 <span id="mav_cmd_request_video_stream_information"></span>[MAV_CMD_REQUEST_VIDEO_STREAM_INFORMATION](../messages/common.md#MAV_CMD_REQUEST_VIDEO_STREAM_INFORMATION) | Send command to request [VIDEO_STREAM_INFORMATION](#video_stream_information). This is sent once for each camera when a camera is detected and it has set the [CAMERA_CAP_FLAGS_HAS_VIDEO_STREAM](../messages/common.md#CAMERA_CAP_FLAGS_HAS_VIDEO_STREAM) flag within the [CAMERA_INFORMATION](../messages/common.md#CAMERA_INFORMATION) message `flags` field.
 <span id="video_stream_information"></span>[VIDEO_STREAM_INFORMATION](../messages/common.md#VIDEO_STREAM_INFORMATION) | Information defining a video stream configuration. If a camera has more than one video stream, it would send one of this for each video stream, with their specific configuration. Each stream must have its own, unique `stream_id`.
 <span id="mav_cmd_request_video_stream_status"></span>[MAV_CMD_REQUEST_VIDEO_STREAM_STATUS](../messages/common.md#MAV_CMD_REQUEST_VIDEO_STREAM_STATUS) | Send command to request [VIDEO_STREAM_STATUS](#video_stream_status). This is sent whenever there is a mode change (when [MAV_CMD_SET_CAMERA_MODE](../messages/common.md#MAV_CMD_SET_CAMERA_MODE) is sent.) It allows the camera to update the stream configuration when a camera mode change occurs.
-<span id="video_stream_status"></span>[VIDEO_STREAM_STATUS](../messages/common.md#VIDEO_STREAM_STATUS) | Information updating a video stream configuration.
+<span id="video_stream_status"></span>[VIDEO_STREAM_STATUS](../messages/common.md#VIDEO_STREAM_STATUS) | Information updating a video stream configuration. <!-- TBD? -->


I can't see VIDEO_STREAM_STATUS in common.xml of current build. Ditto MAV_CMD_REQUEST_VIDEO_STREAM_STATUS
THoughts?

They are there:
https://github.com/mavlink/mavlink/blob/master/message_definitions/v1.0/common.xml#L1686
https://github.com/mavlink/mavlink/blob/master/message_definitions/v1.0/common.xml#L4851

It seems the documentation doesn't yet reflect it.

Thanks. I've prodded Jenkins, and these should appear soon.

hamishwillee · 2019-01-13T07:14:56Z

en/services/camera.md

@@ -93,3 +137,12 @@ Message | Description
 <span id="camera_image_captured"></span>[CAMERA_IMAGE_CAPTURED](../messages/common.md#CAMERA_IMAGE_CAPTURED) | Information about image captured (returned to GPS every time an image is captured). 
 <span id="mav_cmd_image_start_streaming"></span>[MAV_CMD_VIDEO_START_STREAMING](../messages/common.md#MAV_CMD_VIDEO_START_STREAMING) | Send command to start video streaming for the given Stream ID (`stream_id`.) This is mostly for streaming protocols that _push_ a stream. If your camera uses a connection based streaming configuration (RTSP, TCP, etc.), you may ignore it if you don't need it but note that you still must ACK the command, like all `MAV_CMD_XXX` commands. When using a connection based streaming configuration, the GCS will connect the stream from its side. When a camera offers more than one stream and the user switches from one stream to another, the GCS will send a [MAV_CMD_VIDEO_STOP_STREAMING](../messages/common.md#MAV_CMD_VIDEO_STOP_STREAMING) command targeting the current Stream ID followed by a [MAV_CMD_VIDEO_START_STREAMING](../messages/common.md#MAV_CMD_VIDEO_START_STREAMING) targeting the newly selected Stream ID.
 <span id="mav_cmd_image_stop_streaming"></span>[MAV_CMD_VIDEO_STOP_STREAMING](../messages/common.md#MAV_CMD_VIDEO_STOP_STREAMING) | Send command to stop video streaming for the given Stream ID (`stream_id`.) This is mostly for streaming protocols that _push_ a stream. If your camera uses a connection based streaming configuration (RTSP, TCP, etc.), you may ignore it if you don't need it but note that you still must ACK the command, like all `MAV_CMD_XXX` commands. When using a connection based streaming configuration, the GCS will disconnect the stream from its side. When a camera offers more than one stream and the user switches from one stream to another, the GCS will send a [MAV_CMD_VIDEO_STOP_STREAMING](../messages/common.md#MAV_CMD_VIDEO_STOP_STREAMING) command targeting the current Stream ID followed by a [MAV_CMD_VIDEO_START_STREAMING](../messages/common.md#MAV_CMD_VIDEO_START_STREAMING) targeting the newly selected Stream ID.
+
+
+Enum | Description


FYI, just pulled the enums into own section and added the missing ones. Please check.

hamishwillee · 2019-01-13T07:18:45Z

en/services/command.md

@@ -24,5 +24,3 @@ sequenceDiagram;
    Drone->>GCS: COMMAND_ACK


Please ignore this spurious change.

hamishwillee · 2019-01-15T07:20:47Z

en/services/camera.md


 ### Camera Modes

-Some cameras must be in a certain mode for still and/or video capture. The [CAMERA_INFORMATION](../messages/common.md#CAMERA_INFORMATION) message `flags` field uses the [CAMERA_CAP_FLAGS_HAS_MODES](../messages/common.md#CAMERA_CAP_FLAGS_HAS_MODES) bit set to true to inform the GCS that it needs to make sure the camera is in the proper mode prior to sending a start capture (image or video) command. In addition, some cameras can capture images in any mode but with different resolutions. For example, a 20 megapixel camera would take a full resolution image when set to `CAMERA_MODE_IMAGE` but only at the current video resolution if it is set to `CAMERA_MODE_VIDEO`.
+Some cameras must be in a certain mode for still and/or video capture.


OK, I also updated this section to add sequence diagrams. You can see just these changes in f6207b5

And you can see it rendered with sequences here: https://hamishwillee.gitbooks.io/ham_mavdevguide/content/v/cameraupdates/en/services/camera.html#camera-modes

hamishwillee · 2019-01-15T07:23:01Z

en/services/camera.md

+
+The GCS can determine if it needs to make sure the camera is in the proper mode prior to sending a start capture (image or video) command by checking whether the [CAMERA_CAP_FLAGS_HAS_MODES](../messages/common.md#CAMERA_CAP_FLAGS_HAS_MODES) bit is set true in [CAMERA_INFORMATION.flags](../messages/common.md#CAMERA_INFORMATION).
+
+In addition, some cameras can capture images in any mode but with different resolutions. 


@dogmaphobic Not sure about this paragraph here. It is true, but it should probably forward link to information about how this all works using parameters. Basically it seems irrelevant to the actual use of modes as described here.

dogmaphobic · 2019-01-15T17:39:25Z

I think this is all overall OK. We can push it and continue working on it if needed.

One thing missing, though not specific to cameras, the GCS expects a constant flow of heartbeats (1Hz). If a camera stops sending heartbeats, the GCS will remove it from the camera list. Once the GCS starts receiving heartbeats again, the process starts from scratch.

hamishwillee · 2019-01-15T22:36:09Z

Thanks @dogmaphobic. OK, I added a section on connection/disconnection at the top, and moved the "Camera Identification" into basic operations - and then merged. This should be live soon - if it isn't linked yet, it you can see it here

Camera API subedit

fc58c53

hamishwillee requested a review from dogmaphobic January 13, 2019 07:09

hamishwillee commented Jan 13, 2019

View reviewed changes

Remove WIP command protocol changes

9d9787f

hamishwillee commented Jan 13, 2019

View reviewed changes

hamishwillee mentioned this pull request Jan 13, 2019

Adding documentation for video streaming #162

Merged

hamishwillee added 2 commits January 15, 2019 17:39

CameraService: Update camera identification section

bac4c82

Camera: Add mode get/set sequences

f6207b5

hamishwillee commented Jan 15, 2019

View reviewed changes

Add connection/disconnection semantics section

45af7e4

hamishwillee merged commit cb14e49 into mavlink:master Jan 15, 2019

hamishwillee deleted the cameraupdates branch January 15, 2019 22:28

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Camera API subedit #163

Camera API subedit #163

hamishwillee commented Jan 13, 2019 •

edited

hamishwillee Jan 13, 2019

dogmaphobic Jan 13, 2019

hamishwillee Jan 15, 2019

hamishwillee Jan 15, 2019

hamishwillee Jan 15, 2019

hamishwillee Jan 13, 2019

dogmaphobic Jan 13, 2019

hamishwillee Jan 15, 2019

hamishwillee Jan 13, 2019

hamishwillee Jan 13, 2019

hamishwillee Jan 15, 2019

hamishwillee Jan 15, 2019

hamishwillee Jan 15, 2019

dogmaphobic commented Jan 15, 2019

hamishwillee commented Jan 15, 2019


		> Note If no response is sent for a `MAV_CMD_REQUEST_CAMERA_INFORMATION` message, it is assumed camera support is not available and no support for it will be provided by the GCS.
		{% mermaid %}


		The GCS can determine if it needs to make sure the camera is in the proper mode prior to sending a start capture (image or video) command by checking whether the [CAMERA_CAP_FLAGS_HAS_MODES](../messages/common.md#CAMERA_CAP_FLAGS_HAS_MODES) bit is set true in [CAMERA_INFORMATION.flags](../messages/common.md#CAMERA_INFORMATION).

		In addition, some cameras can capture images in any mode but with different resolutions.

Camera API subedit #163

Camera API subedit #163

Conversation

hamishwillee commented Jan 13, 2019 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dogmaphobic commented Jan 15, 2019

hamishwillee commented Jan 15, 2019

hamishwillee commented Jan 13, 2019 •

edited