Actuator Component

fibril_sim/scalar_actuator は scalar command をそのまま MuJoCo actuator control へ渡す最小 virtual driver です。

fibril_sim/motor は MuJoCo native actuator を production-facing motor command、encoder reset、feedback contract へ接続する adapter です。 servo gain、force limit、motor dynamics などの physical actuator semantics は MJCF に置きます。 robot-specific transmission geometry は top-level assemblies に一度だけ記述し、construction 時に MuJoCo actuator gear と Component logical coordinate へ materialize します。

fibril_sim/motion_motor は position、velocity、P gain、D gain、feedforward effort を一つの command として受ける impedance-style actuator adapter です。一つの command が複数の MuJoCo actuator channel を同時に駆動する機器で使います。

MuJoCo 側の要件

actuator には compile 後の MuJoCo actuator name を指定します。 Fibril は command を最終的にその actuator の control value へ適用します。

`fibril_sim/scalar_actuator`

最小設定

components:
  - id: drive
    type: fibril_sim/scalar_actuator
    config:
      actuator: drive_motor

Configuration の項目

Field	Type	Required	Default	Meaning
`actuator`	string	yes		MuJoCo actuator name
`latency_s`	double	no	`0.0`	command transport latency
`delivery_quantization`	string	no	`next_boundary`	`next_boundary` or `strict`
`application_period_s`	double	no	none	actuator application period
`application_phase_s`	double	no	`0.0`	application phase
`timeout_s`	double	no	`0.0`	command timeout
`safe_value`	double	no	`0.0`	initial value and timeout value
`deadband`	double	no	`0.0`	absolute value が閾値未満なら zero にする
`resolution`	double	no	`0.0`	positive の場合に value を量子化する step
`saturation_min`	double	no	none	lower clamp
`saturation_max`	double	no	none	upper clamp

application_phase_s は application_period_s と同時に指定する必要があります。 application schedule は strict quantization で検証されます。

Command processing の流れ

controller command はまず transport latency を通り、release された command が endpoint の held value になります。 application boundary では timeout、deadband、resolution、saturation の順に virtual driver semantics を適用して MuJoCo actuator へ書き込みます。

timeout_s が 0.0 以下なら timeout safe-state selection は無効です。 positive の場合は最後に release された command が timeout を超えると safe_value を適用します。

Saturation と MuJoCo limit

Fibril の saturation_min と saturation_max は virtual driver 側の limit です。 MuJoCo actuator 自身の control limit とは別の層なので、両者を使う場合は意図した hardware limit と physical model limit が一致しているか確認してください。

`fibril_sim/motor`

fibril_sim/motor は MuJoCo native actuator を production-facing motor command / encoder reset / feedback contract へ接続します。 physical servo gain と force limit は MJCF が source of truth です。 external gear、wheel radius、pulley radius などの transmission geometry は SimulationManifest の assemblies が authored source になり、resolved transmission は compile 前の MuJoCo model に反映されます。

対応する physical actuator は次です。

<position>: position command。必要なら virtual-driver が velocity / duty command を position setpoint trajectory へ変換する。
<velocity>: velocity command。必要なら duty command を velocity setpoint へ変換する。
<motor>: torque command。必要なら duty command を effort command へ変換する。
<dcmotor input="position"> / <dcmotor input="velocity">: MuJoCo 3.11 の electrical motor dynamics、current / torque saturation、voltage limit、PID を physical actuator 側に保持したまま position / velocity command を接続する。input="voltage" は production-facing motor command と物理量が一致しないため現在の adapter では受理しない。

Fibril 内で PID force controller を再実装してはいけません。 controller dynamics を test target とする場合は MuJoCo actuator / plugin 等の physical model に置きます。

<actuator>
  <position name="steering_motor"
            joint="steering_joint"
            kp="6"
            kv="0.5"
            forcerange="-2.2 2.2"/>
</actuator>

Manifest は command transport、application timing、logical encoder、feedback semantics だけを追加します。

components:
  - id: steering
    type: fibril_sim/motor
    config:
      profiles:
        device: robomaster_m2006_p36
        transport: robot_can_fast_path
      actuator: steering_motor

profiles は motor 専用機構ではなく SimulationManifest の Component 共通 profile 機構です。 fibril_sim/motor の built-in device profile は現在、controller-visible current feedback の再利用可能な convention だけを提供します。定義値は C++ に埋め込まず、標準 Component と共通の generic profile catalog に保存します。 robot 固有の CAN path や update cadence は project 側の transport profile として組み合わせられます。 instance config は profile 合成後の明示 override として扱われます。

Profile ID	Reusable feedback convention
`robomaster_m2006_p36`	M2006 P36 output-shaft current conversion
`robomaster_m3508_p19`	M3508 P19 output-shaft current conversion
`robstride_rs00`	RS00 current-feedback conversion
`robstride_rs05`	RS05 current-feedback conversion
`c5055_400kv`	C5055 400 KV current-feedback conversion used by the Fibril adapter
`m6c18_170kv`	M6C18 170 KV + current convention used by the current production feedback path

これらは完全な electrical motor model ではありません。外部 gearing、pulley / wheel radius、mechanism inertia / friction、robot 固有 latency、axis 固有 limit は profile に含めません。 MuJoCo dcmotor の resistance、motor constant、inductance、saturation も physical actuator model 側を source of truth とします。

複数 motor が一つの mechanical axis を分担する場合は、Component profile の current conversion を別値で上書きせず assemblies[].actuator_count で台数を宣言します。 resolver は aggregate axis force と device-level current convention から per-actuator feedback current を導出します。 device profile 自体と異なる reporting convention を持つ特殊な単一 actuator instance は、明示 override の対象です。

MJCF physical actuator preset の利用

再利用可能な motor の物理値は Component profile ではなく MJCF default class として定義します。標準 catalog は package://fibril_sim_models/mujoco/actuator_presets.xml から include できます。

<include file="package://fibril_sim_models/mujoco/actuator_presets.xml"/>

<actuator>
  <dcmotor name="drive"
           class="fibril_sim_hw_robomaster_m3508_p19_nominal"
           joint="drive_joint"
           saturation="6 0 0"
           input="velocity"
           controller="4 0 0 0 0 24"/>
</actuator>

現在は specification-derived な fibril_sim_hw_robomaster_m2006_p36_nominal と fibril_sim_hw_robomaster_m3508_p19_nominal を提供します。これらは resistance、Kt/Ke、inductance までを device preset として持ちます。 current/force limit、controller gain、mechanism friction/inertia は consuming MJCF が所有します。 robot-specific transmission geometry は assembly declaration が所有し、resolved actuator gear として mjSpec に materialize されます。実機同定済み effective correction は calibration overlay が所有します。

RobStride のような controller 一体型 actuator は bare motor の electrical preset として扱いません。 Operation mode は次の三つの reusable MJCF class で output-shaft controller を構成します。

fibril_sim_hw_robstride_operation_position：unit P channel。
fibril_sim_hw_robstride_operation_velocity：unit D channel。
fibril_sim_hw_robstride_operation_feedforward：torque feedforward channel。

RobStride Operation packet の kp と kd は固定 device parameter ではなく command field です。 fibril_sim/motion_motor は現在の joint state と packet gain から unit P/D channel の equivalent setpoint を計算し、MuJoCo が actuator force を生成します。複数 channel の合算後 torque limit は consuming joint の actuatorfrcrange に置きます。この構成では外部 reduction を一つの assembly に記述し、三つの actuator channel へ同じ resolved gear を materialize します。 RobStride 内蔵 reduction は product output-shaft contract に含まれるため、assembly の external ratio へ重ねて記述しません。

<joint name="leg_joint" actuatorfrcrange="-35 35"/>

<actuator>
  <position name="leg_position"
            class="fibril_sim_hw_robstride_operation_position"
            joint="leg_joint"/>
  <velocity name="leg_velocity"
            class="fibril_sim_hw_robstride_operation_velocity"
            joint="leg_joint"/>
  <motor name="leg_feedforward"
         class="fibril_sim_hw_robstride_operation_feedforward"
         joint="leg_joint"/>
</actuator>

対応する external reduction は Manifest 側で一度だけ宣言します。

assemblies:
  - id: leg_axis
    component: leg
    transmission:
      type: gear_rotary
      ratio: 2.5

actuatorfrcrange は product peak torque、configured torque limit、configured current limit を external transmission まで反映して決める robot-instance parameter です。 RS00/RS05 の winding R/L は current repository の reusable evidence から確定できないため、推定値を dcmotor preset に入れません。 Operation mode より内側の current-loop lag や torque-speed discrepancy を実機から同定した場合は calibration overlay または dedicated physical plugin の対象とします。

実機同定を継続する robot では、physical actuator parameter を次の三層に分けます。

generic nominal MJCF preset
  + robot-specific assembly / controller / baseline plant
  + versioned persistent calibration overlay
  = calibrated physical actuator model

generic preset には別 robot でも成立する根拠がある device parameter だけを置きます。 robot-specific transmission geometry は assembly に残し、controller mapping と mechanism plant は consuming MJCF に残します。実機 recording から選択した unit-specific または lumped effective parameter は SimulationManifest の parameter_overlays から適用します。 fit 後の値を nominal MJCF へ書き戻す運用にはしません。

RS00 と RS05 には上記の Operation-mode physical controller class を共通利用できますが、generic electrical plant を一意に構成できる reusable evidence はまだありません。 C5055 と M6C18 も generic electrical plant を構成できる reusable evidence がまだないため、physical dcmotor preset を追加していません。 M6C18 の 170 KV 由来 motor constant 自体は再利用可能ですが、MuJoCo の dcmotor default class は正の resistance を必須とするため、R/L を持たない partial physical preset としては表現しません。 controller-visible current convention の Component profile が存在することは、同じ名前の physical plant parameter が確定していることを意味しません。

RobStride の command mode

RobStride の各 command mode は同じ controller として扱いません。 production driver が設定する firmware mode に合わせて Fibril 側の command semantic を分けます。

Production command	RobStride mode	Fibril representation
`MotionTarget`	Operation	`fibril_sim/motion_motor` と unit P/D/FF actuator bank
position target	PositionCSP	`fibril_sim/motor` の position command と MuJoCo position actuator
trajectory target	PositionPP	`fibril_sim/motor` の trajectory generator と MuJoCo position actuator
velocity target	Velocity	`fibril_sim/motor` と MuJoCo velocity-capable actuator
torque / duty target	Current	`fibril_sim/motor` の effort command と current-limit 相当の MuJoCo force envelope

PositionPP の max_vel と acc は trajectory generator の parameter なので、command_velocity_limit と trajectory_acceleration_limit に対応します。 PositionCSP の speed limit は position reference の進み方を制限するため command_velocity_limit で表します。 position loop、speed loop、current loop の実効応答は MJCF actuator または calibration overlay が所有します。 firmware の LocKp、SpdKp、CurKp をそのまま MuJoCo <position kp> にコピーするわけではありません。両者は異なる loop の parameter であり、機構を含む closed-loop response と一対一には対応しないためです。

Configuration の項目

Field	Type	Required	Default	Meaning
`actuator`	string	yes		MuJoCo actuator name
`logical_units_per_joint_unit`	double	no	`1.0`	MuJoCo joint coordinate 1 unit あたりの production-facing logical coordinate。finite non-zero
`command_velocity_limit`	double	no	none	position setpoint slew / velocity command の virtual-driver 側上限 [logical position/s]
`trajectory_acceleration_limit`	double	no	none	trajectory command の加減速上限 [logical position/s^2]。指定時は `command_velocity_limit` と組み合わせて trapezoidal setpoint を生成する
`duty_velocity_scale`	double	no	none	duty `[-1,1]` を velocity setpointへ変換する scale
`duty_effort_scale`	double	no	none	duty `[-1,1]` を direct effort へ変換する scale
`zero_duty_hold`	bool	no	`false`	position actuatorで duty=0 を現在 logical position の hold として扱う
`hold_when_uncommanded`	bool	no	`false`	position actuatorでcommand未受信時に現在 logical positionを保持する
`safe_command`	double	no	`0.0`	command 未受信時と timeout 時の logical setpoint
`command_latency_s`	double	no	`0.0`	command transport latency
`command_jitter_s`	double	no	`0.0`	deterministic seeded command jitter
`command_loss_probability`	double	no	`0.0`	command loss probability
`timeout_s`	double	no	`0.0`	positive の場合に command timeout を有効化
`application_period_s`	double	yes		actuator setpoint application period
`application_phase_s`	double	no	`0.0`	application phase
`feedback_period_s`	double	no	application period	feedback acquisition period
`feedback_phase_s`	double	no	`0.0`	feedback acquisition phase
`feedback_latency_s`	double	no	`0.0`	feedback delivery latency
`feedback_current_per_force`	double	no	`0.0`	actuator force から estimated current への conversion

fibril_sim/motor は kp、ki、kd、effort_limit、motor、transmission、driver を受理しません。 transmission は Component config の field ではなく top-level assemblies の construction metadata です。 servo/controller parameter を adapter に再導入すると MJCF と Fibril の二重 source of truth になるため、受理しません。

対象 joint、actuator kind、physical force range も actuator binding から解決します。 normalized_output は MJCF の actuator forcerange から導出するため、同じ limit を Manifest に重複して指定しません。

position command と encoder reset は logical encoder coordinate を使います。 encoder reset は MuJoCo の joint state を変更せず、以後の position setpoint と feedback position の zero を同じ量だけ移動します。

logical_units_per_joint_unit = s とすると、position と velocity は次の一つの変換から導出します。

logical_position = joint_position * s
logical_velocity = joint_velocity * s
joint_position_command = logical_position_command / s
joint_velocity_command = logical_velocity_command / s

effort command は仕事率を保存する共役変換を使います。

1	`joint_effort = logical_effort * s`

このため command、position feedback、velocity feedback に reciprocal な scale を別々に記述する必要はありません。 assembly に bind しない Component では logical_units_per_joint_unit を直接指定できます。 assembly-bound wheel axis では wheel radius から自動導出するため、Component config に同じ scale を重複記述すると construction error になります。

command_velocity_limit は hardware の back-EMF / torque-speed curve そのものではありません。 virtual driver が command を clamp / slew-limit する場合だけ使用します。 physical shaft-speed capability、power limit、back-EMF 等が test target なら MuJoCo actuator / plugin に表現し、mechanism mass / friction の fitting で代用しません。

MuJoCo 3.11 の dcmotor を使う場合、resistance、motorconst、inductance、saturation、 controller、voltage limit は MJCF に置きます。これらを Component profile に重複定義しません。

Plan inspection は resolved actuator_assemblies と bound actuator から transmission 入力、resolved gear、logical scale、actuator count、joint、command semantic、force range、joint-effort range と native DC motor parameter を確認できます。 Component YAML に物理値を書かなくても、run が実際に使う physical actuator contract を確認できます。

trajectory command は command_velocity_limit を必要とします。 trajectory_acceleration_limit が未指定なら velocity-limited position setpoint、指定されていれば acceleration-limited trapezoidal setpoint を生成します。これは physical motor model ではなく virtual driver の command-generator semantic で、生成された position setpoint を MuJoCo position / dcmotor-position actuator へ渡します。

feedback の applied_effort は mjData.ctrl ではなく MuJoCo の actuator_force を transmission gear で generalized effort に変換して取得します。 position / velocity actuator では ctrl は setpoint であり、effort ではないためです。

一つの production endpoint が複数 command mode を使う場合でも、Fibril が force controller を持つのではなく、 binding 先の physical actuator semantics に対して明示的に変換可能な mode だけを受理します。例えば position actuator の velocity command は setpoint integration、duty command は duty_velocity_scale を介した setpoint integration として扱います。

`fibril_sim/motion_motor`

fibril_sim/motion_motor は三つの actuator endpoint を一つの application boundary で更新します。三つの actuator は同じ one-DoF joint を使い、position、velocity、effort の semantic を一つずつ持つ必要があります。 assembly-bound axis では、一つの external transmission declaration から三 channel へ同じ resolved gear が materialize されます。

components:
  - id: leg
    type: fibril_sim/motion_motor
    config:
      profiles:
        device: robstride_rs00
      joint: leg_joint
      position_actuator: leg_position
      velocity_actuator: leg_velocity
      feedforward_actuator: leg_feedforward
      application_period_s: 0.01
      feedback_period_s: 0.01

MotorMotionCommand の position、velocity、kp、kd、effort_ff は command data です。 kp と kd は non-negative finite value を要求し、effort_ff は joint-side generalized effort として解釈します。 command 未受信時、timeout 時、disable 時は現在の position と velocity を unit P/D channel の基準値に使い、feedforward を zero にして追加 actuator force を発生させません。 feedback の applied_effort は三 channel 合算後の qfrc_actuator から取得します。 feedback_current_per_force は motor-side actuator force に適用するため、外部 reduction がある場合も device profile の current conversion をそのまま再利用できます。