COM_PREARM_MODE Docs needed

[hamishwillee]

Flows from PX4/PX4-Autopilot#12806 (comment)

Reproduced below a bit:

So would I be correct in saying

• Disabled means that this mode doesn't exist - if you try and arm you just go from disarmed to armed.
• Safety button means that you enter this mode when you press the safety button. How then do you move forward to armed?
• Always means that you just go to this mode.

Does this require any docs/mention other than in the param? Frankly I don't understand what it is for, how you move to armed from this state, what an end user needs to do, or when they would set it.

---

You are correct.

How then do you move forward to armed?

As usual: arm switch, or arm stick motion, or MAVLink command

Does this require any docs/mention other than in the param?

Frankly I think some doc is needed here.
In fact, I was not aware of this state before I loaded a custom mixer on an airframe with the safety switch disabled (CBRK_IO_SAFETY), and the actuators started moving right after plugging the battery! This is now fixed with this PR: if you disable the safety switch the system will not prearm on its own by default.

From the user perspective, "prearmed" means "my ailerons move but my propellers do not spin".

In the default case of a system with safety button (COM_PREARM_MODE=Safety button and CBRK_IO_SAFETY=0), the behaviour is

• power up
• all actuators are locked into disarmed position, it is not possible to arm
• safety switch is pressed. The system is now prearmed: non-throttling actuators start moving. System safety is off: it is now possible to arm
• arm command is issued: The system is armed: all actuators move

Now the non default cases:
COM_PREARM_MODE=Disabled:

• power up
• all actuators are locked into disarmed position, it is not possible to arm
• safety switch is pressed. All actuators stay locked into disarmed position. System safety is off: it is now possible to arm
• arm command is issued: The system is armed: all actuators move

COM_PREARM_MODE=Always:

• power up
• The system is now prearmed: non-throttling actuators start moving. Safety is on: it is not possible to arm
• safety switch is pressed. System safety is off: it is now possible to arm
• arm command is issued: The system is armed: all actuators move

---

And now for systems without safety button.

COM_PREARM_MODE=Safety button and CBRK_IO_SAFETY is engaged:

• power up
• all actuators are locked into disarmed position. System safety is off: it is possible to arm.
• arm command is issued: The system is armed: all actuators move

COM_PREARM_MODE=Disabled and CBRK_IO_SAFETY is engaged:
Same as above

COM_PREARM_MODE=Always and CBRK_IO_SAFETY is engaged:

• power up
• The system is now prearmed: non-throttling actuators start moving. Safety is off: it is possible to arm.
• arm command is issued: The system is armed: all actuators move

[hamishwillee]

Not quite sure where this should go. Not as simple as you might think because we don't talk much about the safety switch or arming, and there is some overlap

So proposal is:

1. Add heading for "Arming/Disarming" in Basic concepts. This covers the concept.
2. Add heading for "safety switch" in Basic concepts. In this we just say that it is a physical safety interlock that prevents pre-arming and/or arming.
3. Add note on the physical safety switch on the Safety Page - in addition to the configurable switches currently documented.
4. Perhaps a note on prearming in Flying 101 > Arm the Vehicle