SITL parameters need documenting

[peterbarker]

Feature request

Is your feature request related to a problem? Please describe.

We added support for documenting our SITL parameters in our Wiki and GCS-consumed XML.

However, the parameters are not yet documented. A whitelist was created for the existing SITL parameters - so new parameters need to be documented, older parameters get a free-pass. This is the whitelist: https://github.com/ardupilot/ardupilot/blob/master/Tools/autotest/vehicle_test_suite.py#L2384

We should remove entries from that whitelist so we get parameter docs in places like MissionPlanner's parameter screen while running simulations.

Parameters are documented in https://github.com/ardupilot/ardupilot/blob/master/libraries/SITL/SITL.cpp#L551

Note that this can be a gradual process - even a handful every now and then will whittle away at the list.

Describe the solution you'd like

Parameters documented and removed from the whitelist.

Describe alternatives you've considered

Leaving whitelist in place and forgetting about the problem.

Platform [ X ] All [ ] AntennaTracker [ ] Copter [ ] Plane [ ] Rover [ ] Submarine

[gmazzucchi]

I gladly start documenting the parameters

[gmazzucchi]

Still a work in progress. Any feedback is really appreciated.

[Aaditya2003]

Can i work on this project

[gmazzucchi]

btw there a lot of unused parameters in the whitelist, such as SIM_ACC1_BIAS_X (just to take the first one, but there are many other). Is it because the implementation is yet to be written or they will never be used?

[peterbarker]

btw there a lot of unused parameters in the whitelist, such as SIM_ACC1_BIAS_X (just to take the first one, but there are many other). Is it because the implementation is yet to be written or they will never be used?

They may actually be used - the run SITL and see if they exist

[fibonacci35813]

Can I contribute to this issue?

[peterbarker]

Can I contribute to this issue?

Of course. For anyone else reading this, PRs welcome against the SITL parameter documentation. As much or as little as you want.

[adityaomar3]

There are many parameters which are present in SITL.cpp but not in autotests/common.py, do we have to add them to common.py whitelist?

[astrasourav]

Is this issue still open?

[peterbarker]

General comment - if this issue is still open then there are still parameters to document. I've sketched out these instructions to help work on this issue:

 - generate the parameter documentation with: ./Tools/autotest/param_metadata/param_parse.py --vehicle Copter
 - note the generation of several files in the root directory of the autopilot, including "apm.pdef.xml".  These are the metadata files uses by GCS and Wiki for their page generation
 - choose one format and copy it aside - e.g. "cp apm.pdef.xml master-apm.pdef.xml"
 - find a parameter name in the the get_sim_parameter_documentation_get_whitelist method in Tools/autotest/vehicle_test_suite.py which looks like you could document
 - remove it from the whitelist
 - Open libraries/SITL/SITL.cpp in editor
 - search for your parameter name, but omit the "SIM" part.
   - so if you are going to document SIM_ACC1_RND, search for ACC1_RND to find where the parameter is defined.  It will be a "GROUPINFO" line with no parameter documentation above it.
 - find a a block of documentation for a parameter which looks similar to the one you are documenting; copy and paste that parameter's documentation to be above the GROUPINFO for the parameter you want to document.
 - change the parameter name on the @Param: line
 - work out the variable populated by the parameter.  For example, in
     AP_GROUPINFO("ACC1_RND",     11, SIM, accel_noise[0], 0),
   the variable is a member of an array, "accel_noise"
 - search the entire codebase for that variable name to work out what the variable is actually used for.
 - sometimes be surprised about that; "SIM_ACC1_RND" doesn't do anything random
 - go back and adjust the documentation in SITL.cpp based on your findings
 - regenerate the documentation (e.g.) ./Tools/autotest/param_metadata/param_parse.py --vehicle Copter
 - check the differences between the original documentation and the new documentation eg. "diff apm.pdef.xml-master apm.pdef.xml
 - OPTIONAL, but recommended.  Test the new parameters using SITL "./Tools/autotest/sim_vehicle.py -v ArduCopter --fresh-param".  When the simulation is running, (eg.) "param help SIM_ACC1_RND" will show the new description.
 - OPTIONAL, but recommended: run the CI checks for parameter documentation as they may fail in CI: ./Tools/autotest/autotest.py build.Copter test.Copter.Parameters  
- commit your changes (see Wiki for our required commit message style)
 - push and PR
 - example PR: https://github.com/ArduPilot/ardupilot/pull/27592