Mavlink router - add docs

[hamishwillee]

This provide docs about mavlink router. Note that the official docs are pretty good, but IMO have some flaws:

• It is hard to work out what your options are because the config sample file is buried.
• The syntax for the command line is not listed - though they do show --help. Again, better if this was spelled out to highlight what you can do.
• It shows the broad use, but it is not always obvious what you might do for some specific use cases.

This adds the syntax, the sample config file, and a few use cases. Next time we get a new "how do I do this" we can add to that.

NOTE, the position in hierarchy might change. We should, for example, also talk about mavproxy.

[julianoes]

I've removed myself as a reviewer. I don't actually understand the config options of mavlink-router, and I've used it max 3 times in my life. I'm adding @JonasVautherin instead.

[hamishwillee]

@lucasdemarchi I was wondering if you could advise/review this PR. The purpose is to provide visibility of the tool from MAVLink.io. Also because the docs you have do not clearly outline the "options" (all the information is there, but not as "digestible" as listing the tool help output and better highlighting the sample config).

I see you're doing some improvements too in https://github.com/mavlink-router/mavlink-router/pull/305

[lucasdemarchi]

@hamishwillee added some suggestions above. Also adding here @jbeyerstedt for feedback since he is cleaning up mavlink-router and improving it a lot lately.

My worry is that this has a lot of copy and paste from mavlink-router and it will get outdated. Maybe it should focus on some real world scenarios rather than trying to replicate everything? Dunno, if you think this doc can be kept in sync, it's up to you. We have no plans to do changes that are not backward-compatible, but it's good if docs always points to the recommended options.

[jbeyerstedt]

The readme of mavlink-router definitely needs some more love especially regarding some confusion what the software does and what not. I already started to do some restructuring and re-wording (merged two weeks ago), but the main part is still WIP in https://github.com/mavlink-router/mavlink-router/pull/305.

I think, the mavlink website is a great place to "promote", what tools exist what you can do with them. But I also share the apprehension of Lucas, that having so many details of the syntax will lead to an outdated page quite soon. So a focus on usage examples might be a a good solution?

But I will definitely take a look at your document when finishing https://github.com/mavlink-router/mavlink-router/pull/305. Feel free to add comments there as well. I still need to think of a good solution to document the config file syntax, tough.

[hamishwillee]

@lucasdemarchi @jbeyerstedt Firstly, thanks for commenting and for your work on mavlink-router. I made this change for several reasons.

1. Mavlink routing was not covered here, and needs to be.
2. We keep getting questions on PX4 slack (mainly) about how to address particular use cases. These were mostly answered by the sample config, but that was buried 2 layers down. Further the syntax of the command line was not document. Point is, that it was hard to work out what you can do with this tool

I share your concern. What I think we should do is put this on hold until your WIP is merge. I will try get some time to comment on that next week.

It would be great if your readme could include some of the common use cases as examples. When I get a new question on how to do something we could discuss whether that new question belongs in the set of howtos. Then we could always advise the right way to do the common things. Then I could split this doc back to "hey, mavlink router is a great tool that can do all this" and link?

[hamishwillee]

Moving to draft pending https://github.com/mavlink-router/mavlink-router/pull/305

[lucasdemarchi]

That sounds good. Thanks.

Yeah, particularly about the config documentation: we need to move it somewhere. Maybe add a gh-pages and have all the options documented there?

[hamishwillee]

I don't have a strong opinion about where it should be, but it has to be a lot easier to find than it is now. That's why this PR included it front and centre.