PX4 PositionControl のパラメータを読む：単位・役割・コード上の効き方まとめ

PX4 PositionControl パラメータ早見表

PositionControl クラスの内部変数と、PX4 の実際の設定パラメータ（MPC_* 系）の対応をまとめた参照用資料です。

制御内容の詳細は別記事を参照してください。ここでは 「どのパラメータが、制御のどの段階に、どんな単位で効くか」 を一覧できることを目的としています。

補足：PX4 PositionControlの連載記事で解説した制御内容・コードにでてきたものです。

PX4公式サイトの説明：

• https://docs.px4.io/main/en/advanced_config/parameter_reference
• https://docs.px4.io/main/en/flight_stack/controller_diagrams.html

---

制御フロー（全体像）

位置目標 (pos_sp)
    ↓  [位置P制御]  _gain_pos_p
速度目標 (vel_sp)  ← 速度制限: _lim_vel_horizontal / _lim_vel_up / _lim_vel_down
    ↓  [速度PID制御]  _gain_vel_p / _gain_vel_i / _gain_vel_d
加速度目標 (acc_sp)  ← 加速度FF: _acc_sp
    ↓  [推力ベクトル生成]  _hover_thrust
推力ベクトル (thr_sp)  ← 推力制限: _lim_thr_min / _lim_thr_max / _lim_thr_xy_margin
    ↓  [姿勢生成]  _lim_tilt
姿勢目標 (attitude_sp)

---

1. 位置制御ゲイン

PX4 パラメータ	内部変数	単位	制御段	役割
MPC_XY_P	_gain_pos_p.xy()	1/s	位置P制御（水平）	水平位置誤差 → 水平速度目標
MPC_Z_P	_gain_pos_p.z()	1/s	位置P制御（垂直）	高度誤差 → 垂直速度目標

補足： 位置Pゲインは「位置誤差 [m] に対して何 [m/s] の速度目標を出すか」を決める。大きくすると位置追従が速くなるが、後段の速度制限に当たると効果が頭打ちになる。

---

2. 速度制限

PX4 パラメータ	内部変数	単位	制御段	役割
MPC_XY_VEL_MAX	_lim_vel_horizontal	m/s	速度制限（水平）	水平速度目標の上限
MPC_Z_VEL_MAX_UP	_lim_vel_up	m/s	速度制限（上昇）	上昇速度目標の上限（NED Z 負方向）
MPC_Z_VEL_MAX_DN	_lim_vel_down	m/s	速度制限（下降）	下降速度目標の上限（NED Z 正方向）

補足： PX4 は NED 座標系（Z 下向き正）を使用。上昇は Z 負方向、下降は Z 正方向になるため、符号に注意。

---

3. 速度PIDゲイン

PX4 パラメータ	内部変数	単位	制御段	役割
MPC_XY_VEL_P_ACC	_gain_vel_p.xy()	1/s	速度P制御（水平）	水平速度誤差 → 水平加速度目標
MPC_Z_VEL_P_ACC	_gain_vel_p.z()	1/s	速度P制御（垂直）	垂直速度誤差 → 垂直加速度目標
MPC_XY_VEL_I_ACC	_gain_vel_i.xy()	1/s² 相当	速度I制御（水平）	水平速度誤差を積分し定常偏差を補償
MPC_Z_VEL_I_ACC	_gain_vel_i.z()	1/s² 相当	速度I制御（垂直）	垂直速度誤差を積分し定常偏差を補償
MPC_XY_VEL_D_ACC	_gain_vel_d.xy()	無次元相当	速度D制御（水平）	水平加速度推定値を使って減衰
MPC_Z_VEL_D_ACC	_gain_vel_d.z()	無次元相当	速度D制御（垂直）	垂直加速度推定値を使って減衰

補足：

• P ゲインは「速度誤差 [m/s] に対して何 [m/s²] の加速度を出すか」を決める。
• I ゲインは _vel_int を通じて加速度目標にそのまま加算される（単位は加速度 [m/s²]）。
• D ゲインは setpoint の微分ではなく測定側の加速度 (_vel_dot) にかかる。Derivative kick を避けられる構造。
• 水平 P ゲインは tracking anti-windup の戻しゲイン（arw_gain = 2 / _gain_vel_p(0)）にも影響する。
• 垂直積分項 _vel_int(2) は anti-windup とは別に、毎ステップ先頭で ±g (≒ ±9.81 m/s²) にハードクランプされる。水平方向にはこのクランプはない。
• 水平 tracking anti-windup（ARW）は「要求加速度のノルム > 実際に出せた加速度のノルム」のときだけ発動する。小さい方向への誤差では動作しない。

---

4. 推力制限

PX4 パラメータ	内部変数	単位	制御段	役割
MPC_THR_MIN	_lim_thr_min	normalized thrust	推力下限	出力可能な最小推力（完全ゼロ禁止、最低 10e-4）
MPC_THR_MAX	_lim_thr_max	normalized thrust	推力上限	出力可能な最大推力
MPC_THR_XY_MARG	_lim_thr_xy_margin	normalized thrust	推力配分	垂直制御優先のうえで水平制御に確保する推力余裕

補足： 推力が足りない場面では垂直制御が優先され、余った推力で水平制御が行われる。_lim_thr_min が完全ゼロにならないのは、推力ベクトルから姿勢を推定するためのゼロ除算を防ぐため。

---

5. ホバー推力

PX4 パラメータ	内部変数	単位	制御段	役割
MPC_THR_HOVER	_hover_thrust	normalized thrust	加速度→推力変換	水平姿勢で重力と釣り合う推力。加速度目標を normalized thrust に変換する基準値

補足： ホバー推力は単なる定数ではなく、垂直制御全体の基準点。updateHoverThrust() は、ホバー推力推定値が変わったときに積分項 _vel_int(2) を補正し、制御出力が急変しないようにする。
MPC_THR_HOVER に何を設定しても、内部では HOVER_THRUST_MIN = 0.05 〜 HOVER_THRUST_MAX = 0.9 の範囲にハードクランプされる。

---

6. 傾斜角制限

PX4 パラメータ	内部変数	単位	制御段	役割
MPC_TILTMAX_AIR	_lim_tilt	rad	姿勢生成	推力ベクトルから生成する姿勢の最大傾斜角

補足： 水平加速度を出すには機体を傾ける必要があるが、傾けすぎは危険。小さくすると安全だが出せる水平加速度も小さくなる。

---

7. 分離フラグ

PX4 パラメータ	内部変数	型	制御段	役割
MPC_ACC_DECOUPLE	_decouple_horizontal_and_vertical_acceleration	bool	姿勢生成	true：tilt 計算に垂直加速度を含めない（デフォルト）。false：垂直加速度も含めて body_z を計算

---

まとめ：制御段ごとの対応早見表

制御段	PX4 パラメータ	内部変数	単位
位置P（水平）	MPC_XY_P	_gain_pos_p.xy()	1/s
位置P（垂直）	MPC_Z_P	_gain_pos_p.z()	1/s
速度制限（水平）	MPC_XY_VEL_MAX	_lim_vel_horizontal	m/s
速度制限（上昇）	MPC_Z_VEL_MAX_UP	_lim_vel_up	m/s
速度制限（下降）	MPC_Z_VEL_MAX_DN	_lim_vel_down	m/s
速度P（水平）	MPC_XY_VEL_P_ACC	_gain_vel_p.xy()	1/s
速度P（垂直）	MPC_Z_VEL_P_ACC	_gain_vel_p.z()	1/s
速度I（水平）	MPC_XY_VEL_I_ACC	_gain_vel_i.xy()	1/s² 相当
速度I（垂直）	MPC_Z_VEL_I_ACC	_gain_vel_i.z()	1/s² 相当
速度D（水平）	MPC_XY_VEL_D_ACC	_gain_vel_d.xy()	無次元相当
速度D（垂直）	MPC_Z_VEL_D_ACC	_gain_vel_d.z()	無次元相当
加速度→推力変換	MPC_THR_HOVER	_hover_thrust	normalized
傾斜角制限	MPC_TILTMAX_AIR	_lim_tilt	rad
推力下限	MPC_THR_MIN	_lim_thr_min	normalized
推力上限	MPC_THR_MAX	_lim_thr_max	normalized
水平推力マージン	MPC_THR_XY_MARG	_lim_thr_xy_margin	normalized