pymavlink: content usage request

[hamishwillee]

Pymavlink · GitBook

This setup doc is far more "accessible" than other docs on using Pymavlink - such as https://mavlink.io/en/mavgen_python/ and various ones about the place.

Would it be OK if the general parts of this were pulled into the MAVLink guide? (i.e. I need explicit permission and any conditions required to do so). I'm hoping you will just say "take what you need".

If not, I will add a link to your docs.

[ES-Alexander]

Hi @hamishwillee,

Are you asking for an exemption from the attribution component of the license for these docs? Share-alike is already fulfilled by the mavlink dev guide, and so is non-commercial, so no attribution is the only potential permissions issue.

That said, given your request we are now discussing the best approach for this internally. I already have plans (see end of comment) to restructure our Pymavlink page and improve some of the examples (as part of our ongoing platform transfer, and things like #217), which may be worth considering before stuff gets copied over. @Williangalvani has mentioned

I think everyone would benefit from better documentation at the mavlink side, but I worry about having the same scripts duplicated and maintained to different degrees.

At this stage I'm thinking

our end should have details specific to our vehicles / ArduSub, and generally applicable stuff should be primarily presented on [the MAVLink] side (although it may be used within some of our more detailed examples).

We're also waiting to see whether @rjehangir has any particular thoughts or preference as to what ends up where, and how much (if any) duplication is worth it for us to have once the general MAVLink docs cover the general Pymavlink information, for the convenience of our users being able to get started from a single place. I'll follow up once he's responded.

---

In terms of my planned restructuring, my latest structure plan was/is (copy-pasted WIP):

# Safety
- pilot input (`FS_PILOT_INPUT`)
- leak
- heartbeat
- rc timeout (`RC_OVERRIDE_TIMEOUT`)

# Installation
...

# Examples

Pymavlink has 3 types of messages:
* `command_long_send`: To create a raw package
* `<message_name>_send`: To send simple mavlink messages
* `mavutil`: Functions to abstract some MAVLink messages

## Connecting

### Serial Connection
### Onboard (Companion) Computer
### Control Station (Topside/Surface) Computer

## High Level
### Periodic Events
### Command Protocol

## Controlling the Vehicle
### Send RC
- ArduPilot based around radio-style control
- Inputs are set as PWM channel values
- Ignore a channel via int16_max (65535), but warn that previous value persists
### Send Manual Control (Joystick)
- Abstraction over control aspect
- Can pretend to be a pilot
- Link to joystick functions
- Underlying functionalities generally have explicit messages (link to(/implement?) command protocol)
- All axes must be specified (link to issue of ArduSub not supporting the "ignore" value)
### Arm/disarm
- Vehicle cannot move without arming
### Change flight mode
- Link to flight mode docs
### Set Target Depth/Attitude
- In depth hold/stabilise modes, ArduSub will use control algorithms
- Mention caveats (maximum depth delta, target ignored/reset if vehicle control is actively commanding)
### Control Camera Gimbal
- Via mount commands
- Via servo PWM
- Via RC input (goes to full extent, value specifies speed)
### Set Servo PWM
- Only works for servos that aren't assigned as motors (possibly no function specified?? - confirm)
### Advanced Servo/Gripper Example

## Accessing Parameters
### Read all parameters
### Read and write parameters

## Receiving Data
### Request message interval
- Required for many messages
- TODO: investigate how to receive for `NAMED_VALUE_FLOAT` (request stream?)
- QGC requests a bunch by default, so if it's open then you'll already be receiving several messages (and may not be able to specify rates)
### Receive data and filter by message type
### Advanced Receiving (Message Hooks)

## Sending Data
### Send Message to Control Station software
### Send GPS position
### Send rangefinder / computer vision distance measurement to autopilot

---

If it's relevant, I also have a more full program example using classes and modern Python syntax that will probably have parts extracted from it for our improved docs. You're welcome to take parts of that if it's relevant to do so, although the modern Python syntax may scare off proponents of strong backwards compatibility (I believe Pymavlink is supposed to still be Python 2.7 compatible? Not sure whether that compatibility is also being required for the official examples for it).

[hamishwillee]

@ES-Alexander Thanks for getting back to me.

Essentially any kind of licensing is a pain for re-use. What would be desirable (for me) is if you say "I will copy the relevant section of our docs into your docs under your license, thereby granting you the right to chop and change it as you like without us having to think about this again". Of course that is best case - if you say, just comply with CC-NC-SA 4.0 License I will do so.

Everything you say makes sense. I won't be rushing to integrate this material - plenty of other things to do. So happy to wait for you to do whatever other things you want first. My ideal would be that you made the changes you want on mavlink-devguide yourself in parallel with the work to cut back ardusub docs and we merge at the same time. We iterate the PR together.

---

Zola looks nice. I have looked at heaps of SSGs now, and they all suck in one way or another if you have more complicated requirements. As long as your site doesn't require translation, versioning, deep nesting of sidebar, or support for many pages, most are OK.

FWIW early days, but I'm investigating migrating all the dronecode docs to docsify. Just playing so far, but you can see it here: https://hamishwillee.github.io/multidocsify_test/#/main/en/

For my case this is good because there is no actual migration :-). The approach has no build stage at all - it just loads and renders markdown on the fly. It can do so direct from github, and I can parse the input on the fly to fix up non-working markup. There is no deployment cycle needed which means you can edit from gitbook and see the result immediately on merge. YOu can even point to a PR to render that.

I can pull in my old versions and translations as well.
So far the only change I will have to make is the summary file will need to become an absolute path - ie.. /folder/file.md rather than folder/file.md.

I'm also doing some play to get search working. The inbuilt search is awesome, but uses localStorage, which is limited to 5Mb on chrome. A bigger site may run out - ie such a PX4 docs.

Anyway, not trying to convince you, but I'll be pretty pleased with myself if this works out :-)

[hamishwillee]

Re "If it's relevant, I ...".

My gut feeling is the more information we add the better - and this sound useful. But I'd be lead by you. Generally I'm trying to get experts to contribute and support them to do so as that is the best use of time for everyone.

[hamishwillee]

Last PS. Mavlink-devguide aims to be generic. So if there are ardupilot or PX4 specific bits we try to clearly isolate/identify them.

[ES-Alexander]

We're also waiting to see whether @rjehangir has any particular thoughts ... I'll follow up once he's responded.

Following up (my emphasis),

"I’m happy that he likes our docs and wants to use them! I’m definitely fine with them copying things over and I would be okay providing that without license. I agree maintaining both versions could lead to issues, but the benefits of sharing good examples probably outweigh the risks." - Rusty

Accordingly you have the permission you're after :-)

On this point:

happy to wait for you to do whatever other things you want first. My ideal would be that you made the changes you want on mavlink-devguide yourself in parallel with the work to cut back ardusub docs and we merge at the same time. We iterate the PR together.

Fair enough - I'll keep that in mind when I get to that part. I've got some other things that need doing before I can properly flesh out our restructured pymavlink section, because it will link to other content that I'm planning to sort out first. If there's not a strong rush then I should hopefully make those changes within a reasonable time, but if the priority happens to rise on your end before I've transferred the general parts then you're welcome to copy, chop, and change as you've asked :-)

PS. Mavlink-devguide aims to be generic. So if there are ardupilot or PX4 specific bits we try to clearly isolate/identify them.

Indeed - it's the primary sane approach when documenting an interface that spans multiple implementations 👍

---

Zola has been nice to work with so far, and affords us some nice conveniences that definitely simplify docs development. Fair points on SSGs in general. Zola has nice multilingual support, although we don't currently have docs translations. Versioning and sidebar nesting depth are architectural components that we're working on - we'll see how we go :-)

... FWIW early days, but I'm investigating migrating all the dronecode docs to docsify ...

Always interesting to see different approaches, and I like your demo :-)
Our building is done via CI, and we don't have enough content to have issues with build times. Pointing to a PR for render does seem like a pretty cool idea :-)

[hamishwillee]

Thank you - all sounds good. I'll ping you again if I start doing any kind of migration before you come back to me.