Merge pull request #1327 from bitcraze/krichardsson/hlc-docs

Clarify setpoint priority

docs/functional-areas/sensor-to-control/commanders_setpoints.md

@@ -41,12 +41,38 @@ These can be controlled in different modes, namely:
 So if absolute position control is desired (go to point (1,0,1) in x,y,z), the controller will obey values given setpoint.position.xyz if setpoint.mode.xyz is set to modeAbs. If you rather want to control velocity (go 0.5 m/s in the x-direction), the controller will listen to the values given in setpoint.velocity.xyz if setpoint.mode.xyz is set to modeVel. All the attitude setpoint modes will be set then to disabled (modeDisabled). If only the attitude should be controlled, then all the position modes are set to modeDisabled. This happens for instance when you are controlling the Crazyflie with a controller through the [cfclient](https://www.bitcraze.io/documentation/repository/crazyflie-clients-python/master/) in attitude mode.
 
 
-
 ## High Level Commander
 
 ![high level commander](/docs/images/high_level_commander.png){:width="700"}
 
-As already explained before: The high level commander handles the setpoints from within the firmware based on a predefined trajectory. This was merged as part of the [Crazyswarm](https://crazyswarm.readthedocs.io/en/latest/) project of the [USC ACT lab](https://act.usc.edu/). The high-level commander uses a planner to generate smooth trajectories based on actions like ‘take off’, ‘go to’ or ‘land’ with 7th order polynomials. The planner generates a group of set-points, which will be handled by the High level commander and send one by one to the commander framework.
+As already explained before: The high level commander generates setpoints from within the firmware based on a predefined trajectory. This was merged as part of the [Crazyswarm](https://crazyswarm.readthedocs.io/en/latest/) project of the [USC ACT lab](https://act.usc.edu/). The high-level commander uses a planner to generate smooth trajectories based on actions like ‘take off’, ‘go to’ or ‘land’ with 7th order polynomials. The planner generates a group of set-points, which will be handled by the High level commander and send one by one to the commander framework.
+
+
+### Setpoint priority
+
+The commander framework may receive setpoints from both the High level commander as well as low level setpoints,
+for instance from a user on the ground. Low level setpoints will always have higher priority as they might originate
+from a user that wants to take over control from the High level commander and handle an emergency situation.
+Once the High level commander has been disabled by receiving a low level setpoint, it will not generate any more
+setpoints again until it explicitly is enabled by a call to the `commanderRelaxPriority()` function
+(or `cf.commander.send_notify_setpoint_stop()` from the python lib).
+
+Note that the [supervisor](/docs/functional-areas/supervisor/) will check that there is a continuous stream of setpoints
+received by the commander framework as long as the platform is flying, if not it will take action to protect the
+platform and people around it, possibly ending up in a locked state.
+
+### Switching between High level commander and low level setpoints
+
+There might be a need to go back and forth between the High level commander and low level setpoints. Going from the
+High level commander to low level setpoints is as easy as starting to send the low level setpoints. Going back to the
+High level commander requires a call to the `commanderRelaxPriority()` function (or
+`cf.commander.send_notify_setpoint_stop()` from the python lib) to enable the High level commander again.
+
+Note that it takes a few seconds for the platform to understand that it is not flying after landing, and if you are using
+a script or application that is feeding low level setpoints to the Crazyflie during the landing phase, you have to
+continue to feed zero setpoints for a while to avoid that the supervisor locks the platform. Another option is to
+re-enable the high level commander as it continuously is feeding zero setpoints to the commander framework, also when
+not flying a trajectory.
 
 
 ## Support in the python lib (CFLib)
@@ -57,4 +83,3 @@ There are four main ways to interact with the commander framework from the [pyth
 * **motion_commander_demo.py**: The MotionCommander class exposes a simplified API and sends velocity set-points continuously based on the methods called.
 * **autonomous_sequence_high_level.py**: Use the high level commander directly using the HighLevelCommander class on the Crazyflie object.
 * **position_commander_demo.py**: Use the PositionHlCommander class for a simplified API to send commands to the high level commander.
-