Add documentation for Multi GCS protocol (Draft) #556
Conversation
Davidsastresas
force-pushed
the
PR/Multi-GCS-Docs-Dev
branch
from
14e51c9 to
6a77d8e
Compare
Davidsastresas
force-pushed
the
PR/Multi-GCS-Docs-Dev
branch
from
6a77d8e to
bb766a9
Compare
| @@ -0,0 +1,128 @@ | |||
| # Multi GCS protocol | |||
There was a problem hiding this comment.
Can you make your repo accept change requests from master? That would allow me to subedit freely (ideally) and merge comments. Likely to be much faster and less work on you.
| @@ -0,0 +1,128 @@ | |||
| # Multi GCS protocol | |||
| ## Introduction | |||
There was a problem hiding this comment.
Might be worth first starting with the "use case" like:
This protocol allows a GCS to request control of a MAVLink system from a single component (usually the autopilot), and for the other components of the system to determine the controlling GCS and set their controlling GCS to match.
Note that the API only provides mechanisms for managing and handing over control of the system: it does not provide any security layer.
| @@ -0,0 +1,128 @@ | |||
| # Multi GCS protocol | |||
| ## Introduction | |||
There was a problem hiding this comment.
FYI, need to change the "autopilot" focus if we allow the CONTROL_STATUS to be emitted by other components.
| Note that the pilots of both GCS should co-ordinate safe handover offline. | ||
| It is also possible for a GCS to request control of a specific component rather than the whole system (though this is not recommended). | ||
| In this case the command should be sent to the specific component, which should also emit CONTROL_STATUS to indicate its owner (this component would ignore the CONTROL_STATUS set by the autopilot). | ||
| The flow is otherwise the same. |
There was a problem hiding this comment.
We also need to add that:
- System can be uncontrolled
- If the autopilot ('controlling component') loses its connection to the controlling GCS we need to make it clear how the ownership lapses.
- IMO we don't want a GCS that has been turned off to be the controller, but nor do we want a vehicle that flies out of range and then starts to return to have no owner (though this is not critical as a vehicle will accept commands from any GCS if it has not owner)
- So I "think" maybe a model like: after short connection break, set takeover allowed. After a bit longer, make uncontrolled.
| In this case the command should be sent to the specific component, which should also emit CONTROL_STATUS to indicate its owner (this component would ignore the CONTROL_STATUS set by the autopilot). | ||
| The flow is otherwise the same. | ||
|
|
||
| ### Multi GCS protocol messages |
There was a problem hiding this comment.
We have standard names for some of these. Note all headings are first letter of each word capitalised and should "by default" indent by one level from previous (ie this is H2).
| ### Multi GCS protocol messages | |
| ## Message/Enum Summary |
| | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | <a id="MAV_CMD_REQUEST_OPERATOR_CONTROL"></a>[MAV_CMD_REQUEST_OPERATOR_CONTROL](../messages/development.md#MAV_CMD_REQUEST_OPERATOR_CONTROL) | Request control of a system. | ||
|
|
||
| ### Workflow diagrams |
There was a problem hiding this comment.
Let's add some more structure. Maybe also add workflow where no GCS is in control, and for control of a specific component? Maybe also a heading for "Vehicle loses connection" (with no diagram)
| ### Workflow diagrams | |
| ## Operations | |
| ### Request Control When Takeover Allowed | |
|
|
||
| [](https://mermaid-js.github.io/mermaid-live-editor/edit#pako:eNrdVV9v2jAQ_yqnvKxItAqt9pJNSBmgqdqAjdA-IUUmvoDVxGaOA0JVv_vO4KSQlbWT2B7GC87Zd_n9uXMevURx9AKvwB8lygT7gi00yz_MJNBvxbQRiVgxaeBzL4JLuH5_8-vWPS5FkiFtd07n-fstqQyCWqM-zArgk1aMJ6ww0BuPppPx1ziahtO7KICRmiu-BSEhUdJolcHHue5SVrQtBIfbOh6Ae8VB4ctut8YdNEpXdQpbJxYyflsd_w_qwL7QqOZ8AMYuaQEbEqkAo0BbC0iAI5okF6BMlU6EXAArHuwfPYJhD2hL7t9Q1yWgR7oOw_u4N-zHk8H3u0E0jcffBpNwOp7EjkNQoSfLWG4zfLjYK-vw2BdWkCwaiciRtyFhEuYItC4TgxxSrXIoUHLUreOi1wF04KJBr3HmZneGZZnaACuNyhk1UE2y9aqxw2E46sdh70tT8SM1eo6HIME1k0WKmpCT9s6MM_lubXWbFYN4Rw35jmYVBBd8ZkyBbetMXXwWFC-27q2xCkqy6mAqVQprB7lzKte347xxavsnW_9qjzss6iHhgst31SQg9Z2bBtuIu7PCwEZkme1Iur-kadK5Op4T__-ckzZ5aZaqXCxBaI0Zru0NrMViaaxdrVf7-21jRMa8cBORncWBSRzm28o_Z1LyPH6_M-kMne__rfnz_xkKr-3lqHMmOH2eHy2mmWeWmOPMC2jJMWVlZmbeTD7RUZsbbWXiBUaX2Pa0bQIvSFlW0FO54sxU3_ZGdMCFUdoFn34CXbSSUw) | ||
|
|
||
| Diagram 2 - Now one of them asks for control enforcing being asked before other GCS takes over. When the other GCS takes over, the original GCS in control just requests again control without enforcing being asked before. This situation is interesting so the vehicle is never with no GCS in control. An alternative approach is in diagram 3. |
There was a problem hiding this comment.
| Diagram 2 - Now one of them asks for control enforcing being asked before other GCS takes over. When the other GCS takes over, the original GCS in control just requests again control without enforcing being asked before. This situation is interesting so the vehicle is never with no GCS in control. An alternative approach is in diagram 3. | |
| ### Request Control When Takeover Not Allowed | |
| Diagram 2 - Now one of them asks for control enforcing being asked before other GCS takes over. When the other GCS takes over, the original GCS in control just requests again control without enforcing being asked before. This situation is interesting so the vehicle is never with no GCS in control. An alternative approach is in diagram 3. |
|
@Davidsastresas Firstly, thanks very much. I'm grateful that you have started this documentation. I have given it a rough review and added some suggestions. I want to resolve the detail before I put too much effort into this - hopefully next week.
Its a bit of a balancing act. We want to have enough that people can get a flavour for the messages without having to navigate - that makes the document more readable. On the other hand, we don't want to duplicate everything. I tend to copy the description from the message but not the whole detail - its a summary. I'll probably add just a little more than is there. Can you unrestrict editing on your fork of the repo ? |
Co-authored-by: Hamish Willee <[email protected]>
Co-authored-by: Hamish Willee <[email protected]>
Co-authored-by: Hamish Willee <[email protected]>
Documentation for mavlink/mavlink#2158. It is the first time I work from scratch on this kind of documentation, so I marked it as draft to keep iterating. So far I pretty much copied the ongoing description on that PR. I am not sure if we need to add the messages manually to development.md, to link them on multi_gcs.md.
Also, should we extend here on the explanation of the messages/commands or just the links to development.md would do it? Let me know your thoughts.
Sorry for presenting such a bare draft, hopefully next time I will get better at this and require less of your time. Thank you!