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.

[hamishwillee]

Can we filter multiple messages - if so - how?

[lucasdemarchi]

it's comma separated

[lucasdemarchi]

And although the old name should continue to work, it 's currently being renamed to AllowMsgIdOut

[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 mavlink-router/mavlink-router#305

[lucasdemarchi]

the wording regarding "from" and "to" could be improved. mavlink-router doesn't differentiate endpoints like this

[lucasdemarchi]

Traffic is also routed between 192.168.7.1:14550 and 127.0.0.1:14550 if a packet that is send to a system/component available in that endpoint (or if it's a broadcast).

I'm preferring to document it like:
mavlink-routerd -e 192.168.7.1:14550 -e 127.0.0.1:14550 -e /dev/ttyS1:1500000

so it's clear they are all "Endpoints". I realize this is not what the README.md is currently saying. Maybe one thing that could help is to show how the command line options translate to config, which is maybe clearer to understand. In this example it would be:

[UartEndpoint uart0]
Device = /dev/ttyS1
Baud = 1500000

[UdpEndpoint udp0]
Address = 192.168.7.1
Port = 14550

[UdpEndpoint udp1]
Address = 127.0.0.1
Port = 14550

[lucasdemarchi]

This is equivalent to:

[UdpEndpoint udp0]
Address = 192.168.7.1
Port = 14550

[UdpEndpoint udp1]
Address = 127.0.0.1
Port = 14550

[UdpEndpoint udp0]
Address = 192.168.7.1
Port = 14550

[UdpEndpoint udp2]
Mode = server
Address = 0.0.0.0
Port = 24550

the missing -e only matters for an UDP endpoint and makes that UDP endpoint be in "server mode". In other words, it will listen for packets in that specific port instead of sending to that specific port.

[lucasdemarchi]

maybe we should also mention the provided systemd service. Provided one installed via package or via ninja -C build install, the normal systemctl <start|enable> mavlink-router can be used to make it permanent (which makes sense when it's running on a companion computer) rather than starting it manually or via hack scripts.

[lucasdemarchi]

this is deprecated, please use "server"

[lucasdemarchi]

I think a better or more realistic example here would be to use a broadcast address. This has a special behavior: packets are sent as broadcast until something responds back. After the response we "lock into that ip:port that provided the reply". This way you don't have to bother with your desktop/laptop having a different IP assigned

[lucasdemarchi]

it's comma separated

[lucasdemarchi]

And although the old name should continue to work, it 's currently being renamed to AllowMsgIdOut

[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 mavlink-router/mavlink-router#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 mavlink-router/mavlink-router#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 mavlink-router/mavlink-router#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.