Homing 用パラメータの校正 (velocity_home / stroke)

Homing state machine が使う数字を事前に測る。VELOCITY mode では velocity_home と stroke の 2 つで済む

要点 (現行 VELOCITY mode、2026-09 以降): Homing に要る param のうち機構ごとに必ず違うのは velocity_home (押し当て速度)、stroke (機構の可動範囲) の 2 つだけ。残り (ramp 時間・v_min 幅・電流マージン係数など) は default で 8 割の機構が通る。

移行前提: 初期の DUTY mode では duty_home (押し当て duty) + duty_min_move (動き出し duty) + min_speed (duty_home で出る実測速度) の 3 つを校正する必要があった。VELOCITY mode に切り替えたことで duty ramp 校正が不要になり、目標速度を直接指定すれば済むようになった (移行理由は current-based-endstop-detection の DUTY/VELOCITY 節)。

2 つの数字と決め方 (現行 VELOCITY mode)#

数字	単位	決め方
`velocity_home`	rad/s or m/s	「壁に押し当てる速度」。ゆっくり (0.1〜1 rad/s) 押し付ける方が電流スパイクが立ちやすく、ギア破損リスクが低い。default 0.5 rad/s、機構質量が大きい / ギア弱いなら 0.1〜0.2 に下げる
`stroke`	rad or m	図面値。`encoder.gain` で機構側の単位に変換済みの feedback.position と揃える。`timeout_ms = stroke / velocity_home × 3` の目安で timeout を出す

VELOCITY mode の校正手順は本質的に「実機で試して速度と方向を決める」だけ:

velocity_home に候補 (例 0.5 rad/s、機構の想定 stroke / 1 s くらいの速度) を入れて trigger
壁に到達して LIMIT_HIT で DONE すれば OK。到達前に stall 誤検知するなら k_current_margin を上げる (default 3 → 5)
壁到達エネルギーが強すぎるなら velocity_home と current_limit_calib (calib 中の cap) を下げる

DUTY mode 時代のような duty ramp 校正 (duty_min_move 実測) は不要。

旧 DUTY mode の校正手順 (参考、2026-09 以前)#

VELOCITY mode 移行前は以下の 3 数字を校正していた。RoboMaster MD 以外の PWM duty 系 MD (ODrive の open-loop / VESC の duty など、firmware が電流を regulate しないもの) では今も有効な方法。

数字	単位	決め方
`duty_home`	duty [-1, 1]	`duty_min_move × 2〜3`。`duty_min_move` は「動き出した最小 duty」を duty ramp で実測
`stroke`	rad or m	図面値。`encoder.gain` で機構側の単位に変換済みの feedback.position と揃える
`min_speed`	rad/s or m/s	`duty_home` で走らせた時の実測平均速度。ramp/settle を除いた末尾区間だけで平均する (加速中を含めると小さくなる)

旧 DUTY 校正手順 #

前提: 機構が limit 位置ではなく、少なくとも数十度は自由に動ける状態から開始する。

OFF baseline (duty=0 で 2 秒): 電流の offset, σ_off と速度ノイズ σ_v_off を測る
v_min の自動決定: v_min = max(3·σ_v_off, 0.05 rad/s) — 「動いてる」判定の閾値。encoder 分解能とノイズを自動で吸う
Duty ramp: duty=0.03 から 0.01 刻みで上げ、|v| > v_min を最初に満たした値が duty_min_move
duty_home で走行: duty_home = 2.5 × duty_min_move を印加、末尾 0.3 s の平均速度が min_speed
timeout の導出: timeout_ms = stroke / min_speed × 1000 × 3 (安全率 3)

なぜ 3 つで足りるか #

Default で通る「上級パラメータ」6 個:

Param	Default	なぜ default で良いか
`ramp_time_ms`	200	soft-start に十分。慣性極端に大きい機構だけ 400 に上げる
`move_baseline_ms`	100	実走中の I_move を測る時間。10 サンプル/100Hz で足りる
`v_min_hold_ms`	50	動いている確信の時間。短すぎると誤検出、長すぎると遅延
`start_gate_ms`	100	加速の完了を待つ時間。ほとんどの機構は 100 ms 以内で速度立ち上がる
`k_current_margin`	3.0	stall 閾値 `I_move + k·σ_move` の係数。3σ は 99.7% で誤検出低い
`backoff`	0.05 rad	検出後の退避量。5 度弱、次動作の余白として妥当

これらは物理定数に近く、機構個体差の影響が小さい。ダメだった機構だけ 1 個ずつ override する運用にすると yaml 5 行で済む。

Param 名は単位を含めない #

stroke_rad / min_speed_rad_s のように単位を接尾すると、linear 軸 (単位 m) の機構で意味が変わる。encoder.gain で機構側の物理量 (rad or m) を吐く前提なら、param 名は stroke / min_speed / backoff にして「feedback.position と同じ単位」で受けるほうが素直。

実行時に測る値 (yaml 化しない)#

offset, σ_off: S0 で毎回測る
I_move, σ_move: S3 で毎回測る
I_stall: S4 で観測、log 用

これらは温度・機構状態で変わるので param 固定しない。homing 実行のたびに現場で拾う。

無負荷検証で分かるのは限られる #

無負荷モータでの校正は基本値の確認までで、実機構の値は違う:

duty_min_move は機構ジャム・重力・摩擦で 3〜5 倍になる
min_speed は減速比で 10〜100 倍下がる
I_stall は無負荷では検出できない (壁がない)

実機構が付いてからもう一度校正が正しい。