Parameter naming standards/guidelines

[timtuxworth (Tim Tuxworth aka TimthePlaneman)]

We always say the best thing about ArduPilot is there are a thousand+ parameters and the worst thing about ArduPilot is there are a thousand+ parameters…

I’ve been thinking that it might help if there were at least some guidelines for parameter names, (if not “standards”) which were generally followed. It really would help to improve the useability of ArduPilot for non-developers.

So sure there are reasons for some of the naming issues. The 16 character limit on the length of a parameter name (which really should be addressed), does create challenges.

So I’m going to take a stab at suggesting some guidelines. I’m doing it here so there can be discussion, and I plan to CHANGE my proposals (this post) as the discussion progresses.

This is just a suggestion for go-foward new parameters or any refactoring, it’s not a suggestion for a wholesale renaming of parameters now, (even though I use some existing parameters as examples).

Interestingly most of the Q_ parameters seem to follow these rules.

General Principles

• Names should have a logical structure (see below)
• Names should not have information embedded that is included in the metadata (e.g. units)
• Abbreviations should follow some standard rules
• Certain standard agreed abbreviations and qualifiers should be used
• Abbreviations should generally be used even if not needed due to the 16 character limit (this should be able to be dropped if the 16 character limit can be fixed)
• Underlying sub-system names should be hidden from end users
• use pitch, roll and yaw instead of elevator, aileron and rudder

Names should have a logical structure

It helps people to understand things when there is a logical structure that makes sense, but with ArduPilot there can’t be just one logical structure because there are several different kinds of concepts at play. I think this doesn’t mean we need to fall back to a “case by case” basis, I think it can mostly be done by having several broad categories of structures that can be applied. Here are my suggestions:

Entity_attribute, Entity_attribute_qualifier/function.
Feature_attribute, Feature_attribute_qualifier

Lets look at each one of these with some examples:

Entity_Attribute or Entity_Attribute_qualfier/function
I think “TRIM_PITCH” is a good example of this, because as far as I can see it is so obvious that “PITCH” is the entity here. Pitch can exist by itself, but trim makes no sense unless applied to something. So this should be PITCH_TRIM, ROLL_TRIM, YAW_TRIM, THR_TRIM and not TRIM_PITCH, TRIM_ROLL, TRIM_THROTTLE and TRIM_YAW - trim is the attribute and it only makes sense when it is an attribute of an “entity” - pitch, roll, yaw, throttle, etc.

By adding the qualifier at the end you get sensible things like PITCH_TRIM_MAX and PITCH_TRIM_MIN.

I would argue that this would make strange parameters like KFF_THR2PTCH_MIX and KFF_RDDRMIX a lot easier to understand and find because they would be something like:

• PITCH_THR_MIX
• YAW_ROLL_MIX

Now you could use the same thing for FENCE. Fence is an “Entity” and other things that apply to fences should be FENCE_attributes. All the existing FENCE_ parameters comply with this rule.

Following this logic, WP_MAX_RADIUS should have been WP_RADIUS_MAX, or maybe WP_RAD_MAX. WP_LOITER_RAD is a good name by this rule, but RTL_RADIUS should probably have been RTL_LOITER_RAD.

I think something using the word “cruise” was suggested as a replacement for FBW_ARSPD_MIN and FBW_ARSPD_MAX. That probably makes a lot of sense. These don’t really have anything to do with FBW, so these might become

• FBW_ARSPD_MIN → CRUISE_ARSPD_MIN
• FBW_ARSPD_MAX → CRUISE_ARSPD_MAX
• FBW_ELEV_REV becomes something like CRUISE_PITCH_REV

Feature_attribute or Feature_Attribute_qualifier/function
Takeoff or landing are good examples of these. They are features or functions, so all things that apply to each should start with the feature TKOFF and LAND.

The existing TKOFF_THR_MINSPD - probably should be TKOFF_THR_ARSPD_MIN but that’s > 16 chars, so as is makes sense.

USE_REV_THRUST is a good example of an existing parameter that might be better if it follows this rule - should be THRUST_REV_USE (Feature_attribute_qualifier).

Abbreviations and Qualifiers

English has a fairly standard set of rules for abbreviations. You can find lots of suggestions online. I like these simple rules

1. Shorten long words by using the beginning of the word. THROTTLE becomes THR.
2. Omit vowels starting at the right and once the vowels are gone, start dropping consonants from the right - SPOILER becomes SPOILR or SPLR or SP.
3. Use just the first and last letter of monosyllabic words - MOUNT becomes MT
4. Use acronyms when it makes sense - eg. FBW for Fly by Wire, RTL for Return to Launch

Following these rules Differential Spoiler should probably have become DIFFSPLR or DIFFSP (rather than DSPOILR)

Some standard abbreviations should be used as a general rule:
MAN - rather than MANUAL
FLTMODE (or FLTMD?) for Flight mode
YAW, PIT, RLL, THR for yaw, pitch, roll, throttle - IMO PTCH should be deprecated.
_MASK - used for all bit masks, except for _AXES which is a special case bitmask
_OPTIONS - used for options
TH for threshold because the current use of THR can easily be confused with THRottle
ARSPD for airspeed - never AIRSPEED. SPD can be used if 16 characters is a challenge but should be avoided if possible.
_LIM not _LIMIT for any limits - e.g. LEVEL_ROLL_LIMIT should have been LEVEL_ROLL_LIM
ALT should aways be used for altitude - HEIGHT, HGT, etc. should never be used.

Again - This is just a suggestion for go-foward new parameters or any refactoring, it’s not a suggestion for a wholesale renaming of parameters now, (even though I use some existing parameters as examples).

Please add suggestions, additions, improvements or disagreements below and I’ll update the main article based on the discussion.

[cuav_le]

Once adjusted, the following adverse consequences will occur:

1. All users must relearn the new setup method
2. All historical tutorials are invalid. Users need to judge by themselves which historical tutorials and existing tutorials are correct.
3. Ardupilot will have to add many new version settings functions, which will make the system too complex.
4. This will take a lot of time, which can be used for more valuable new feature development and wiki improvements.
   I want to share the manufacturers’ worries. We often tell users repeatedly how to set them because parameter names have been modified, and confirm which version of firmware the user is using (it should be noted that many users use historical versions)
   Finally, I think ardupilot is not very usable because it does not require users to modify parameters like DJI does. For the end user, he just needs to fly, and the adjustment should be left to the manufacturer’s professional engineers. In other words, what ardupilot needs is an open machine operator who is willing to share. For professional engineers, parameter names don’t matter because gcs are annotated and there are tons of tutorials in the internet.

[rfriedman]

One of the concerns raised was the user increase in cognitive load when parameter names change. I know AP supports parameter migration, but have you considered any additional ways of documenting parameter renames so that users can find information across versions easier?

[Yuri_Rage]

The last time this came up, I was all for homogenizing things, making pretty names that are well organized and easy to find. But I think we are framing the problem improperly.

The AP user experience can be frustrating not just because the parameters are named inconsistently…but more because there is an expectation that the user interact directly with a giant list of parameters in the first place.

This is a bit like expecting Windows users to customize their experience using regedit. Sure, it can be done, but no one wants that.

There should have been a set of standards long ago to make the parameters easier to navigate from a developer standpoint and also to homogenize the code at large and its documentation alike. The resulting fragmentation is piss poor at this point and is evidenced not just by a lack of standards in parameter naming but also garbage documentation that I’ve come to understand is largely a side effect of partners paying for features but not paying to document - perhaps a rant for another day.

But from a user standpoint, no one should have to care what the parameters are named. That should be abstracted away by configuration software.

Not one iota of effort should be put into renaming parameters before the existing ones are properly and thoroughly documented. And if you don’t want to document the parameters, put that effort toward making the user experience worth a Bristol 7 instead of 1990s regedit.

[amilcarlucas]

This is my stab at the problem:

How to methodically tune (almost) any multicopter using ArduCopter 4.4.x

[Cinewhoop Diatone Taycan MX-C] For illustrative purposes, we will use the small 3’’ multicopter depicted above, but the tuning sequence we developed at IAV GmbH will work on almost any other multicopter. This method uses the latest available ArduPilot WebTools, some of the new features of ArduCopter 4.3 and best practices from the Ardupilot Community. We will detail the firmware parameters to change, the sequence of how to change them, help you to find the value for each parameter, explain …

It separates the problem in small steps. All parameter files are automatically documented by this
param_docs_update.py (10.8 KB) python script.

It would be nice if ArduPilot would in the future provide version dependent apm.pdef.xml files on firmware.ardupilot.org/<Vehicle>/<fw-version>/apm.pdef.xml

[timtuxworth (Tim Tuxworth aka TimthePlaneman)]

This is interesting @amilcarlucas, but could you provide some “generic” copter, plane … configuration? I plugged in my Holybro QAV250 to this, and it immediately suggested changes that would break (such as enabling DSHot where this drone doesn’t support it).

[amilcarlucas]

Yes, I would love to do that. If you change the parameter values and their “change reason” fields using the ArduPilot Methodic Configurator Software and send me the resulting .zip file (the program creates the .zip file automatically at the last .param file) I could include that vehicle as a second example.

This way We could have one example for copter and one for plane.

Regarding generic configuration for all, that is just not possible. but what is possible is to have some templates with commonly used options for most use cases. People can sill choose to write or not to write the parameters on a per parameter basis and they can and must change the parameters to suit their needs.