OpenArm Control

Reusable kinematics and control utilities for OpenArm, backed by MuJoCo and mink.

Install

uv sync

Usage

`Kinematics`

Poses are float32[7] = [px, py, pz, qw, qx, qy, qz], expressed in the scene's arm_origin site frame by default (--origin-frame world restores world-frame poses).

fromopenarm_controlimportKinematics, IKParams, ArmSetup# FK onlykin=Kinematics(setup)
pose=kin.fk("right", joints) # float32[7]pose_r, pose_l=kin.fk_bimanual(r, l) # single mj_forward# IKkin=Kinematics(setup, IKParams())
kin.set_target("right", pose_r)
kin.set_target("left", pose_l)
result=kin.solve() # float32[16] right[8]+left[8]

`IKParams`

Solver configuration passed to Kinematics. Key fields are listed below; all fields have defaults.

Field	Default	Description
`position_cost`	`12.0`	Position task weight
`orientation_cost`	`1.5`	Orientation task weight
`lm_damping`	`0.01`	Per-task Levenberg-Marquardt damping
`damping`	`0.1`	Global Tikhonov regularization
`solver`	`"daqp"`	QP backend
`posture_cost`	`0.0`	Full home posture task weight (0 = disabled)
`dt`	`0.004`	Outer control period, divided across IK iterations
`max_iters`	`5`	IK sub-iterations per solve
`velocity_limits`	`None`	Joint-name to velocity-cap mapping in rad/s; `None` keeps position-only limits
`frame_position_error_limit`	`0.02`	Total position-error request per outer IK solve
`frame_orientation_error_limit`	`0.25`	Total orientation-error request per outer IK solve
`nullspace_cost`	`8.5`	Fixed-home nullspace posture cost
`nullspace_return_rate`	`1.6`	Nullspace return rate in s⁻¹
`joint_braking`	`True`	Enable preventive braking when velocity limits are active
`joint_braking_distance`	`0.2`	Joint-limit braking distance in radians
`singularity_max_approach_rate`	`0.25`	Maximum singularity-ratio approach rate
`kinetic_energy_cost`	`2e-5`	Kinetic-energy regularization cost

Build from CLI args with register_ik_args + ik_params_from_args:

python your_ik_node.py --tick-hz 250 --limit-velocity

Without --config, --limit-velocity uses the built-in per-arm caps [2, 2, 3.14, 3.14, 6.3, 6.3, 6.3] rad/s. An optional YAML override uses a seven-entry arm_velocity_limits list:

arm_velocity_limits: [2.0, 2.0, 3.14, 3.14, 6.3, 6.3, 6.3]

python your_ik_node.py --limit-velocity --config ./ik_limits.yaml

Constrained IK behavior

A bare IKParams() instance enables four complementary mechanisms:

Frame-error bounding limits the Cartesian correction requested by one outer solve while retaining the full target for subsequent cycles. Position bounding activates smoothly with target linear speed and remains latched while accumulated position lag is significant; orientation bounding is always active when configured.
Nullspace posture regulation guides the redundant arm motion toward the initial home posture without applying a full joint-space posture objective.
Singularity approach limiting slows only motion that moves the arm toward a poorly conditioned configuration.
Kinetic-energy regularization provides a weak mass-matrix-based tie-breaker between kinematically similar solutions. It is not inverse dynamics or gravity compensation.

Frame-error bounding limits accumulated feedback correction, not target velocity, and does not replace joint velocity limits. The full-joint home PostureTask is a separate optional objective controlled by posture_cost and is disabled by default.

The bare library default leaves hardware-specific per-joint velocity limits opt-in: provide velocity_limits directly or use --limit-velocity. The CLI flag selects the built-in caps unless --config overrides them. Enabling these limits replaces the position-only arm limit with one recoverable position/velocity envelope, so a command already slightly outside a position bound can return over multiple feasible steps. Preventive braking then reduces only the velocity approaching a nearby position bound; it is enabled by default with velocity limits and can be disabled with --no-joint-braking.

These limits constrain the QP solution. A downstream driver may apply its own independently configured execution-layer velocity envelope; the two sets of caps are not required to match.

Set both frame-error limits to zero to remove frame-error bounding. Set nullspace_cost, singularity_max_approach_rate, or kinetic_energy_cost to zero to disable the corresponding mechanism. These are kinematic command-layer mechanisms, not a certified whole-robot safety controller.

The remaining curve-shape and threshold parameters are regular IKParams fields but are intentionally not exposed as CLI flags. Call update_measured_state() with fresh driver qpos for state-aware limits; the caller owns freshness and should call clear_measured_state() when that state expires.

License

Licensed under the Apache License 2.0. See LICENSE.txt for details.

Code of Conduct

All participation in the OpenArm project is governed by our Code of Conduct.

OpenArm Control

Reusable kinematics and control utilities for OpenArm, backed by MuJoCo and mink.

Install

uv sync

Usage

`Kinematics`

Poses are float32[7] = [px, py, pz, qw, qx, qy, qz], expressed in the scene's arm_origin site frame by default (--origin-frame world restores world-frame poses).

fromopenarm_controlimportKinematics, IKParams, ArmSetup# FK onlykin=Kinematics(setup)
pose=kin.fk("right", joints) # float32[7]pose_r, pose_l=kin.fk_bimanual(r, l) # single mj_forward# IKkin=Kinematics(setup, IKParams())
kin.set_target("right", pose_r)
kin.set_target("left", pose_l)
result=kin.solve() # float32[16] right[8]+left[8]

`IKParams`

Solver configuration passed to Kinematics. Key fields are listed below; all fields have defaults.

Field	Default	Description
`position_cost`	`12.0`	Position task weight
`orientation_cost`	`1.5`	Orientation task weight
`lm_damping`	`0.01`	Per-task Levenberg-Marquardt damping
`damping`	`0.1`	Global Tikhonov regularization
`solver`	`"daqp"`	QP backend
`posture_cost`	`0.0`	Full home posture task weight (0 = disabled)
`dt`	`0.004`	Outer control period, divided across IK iterations
`max_iters`	`5`	IK sub-iterations per solve
`velocity_limits`	`None`	Joint-name to velocity-cap mapping in rad/s; `None` keeps position-only limits
`frame_position_error_limit`	`0.02`	Total position-error request per outer IK solve
`frame_orientation_error_limit`	`0.25`	Total orientation-error request per outer IK solve
`nullspace_cost`	`8.5`	Fixed-home nullspace posture cost
`nullspace_return_rate`	`1.6`	Nullspace return rate in s⁻¹
`joint_braking`	`True`	Enable preventive braking when velocity limits are active
`joint_braking_distance`	`0.2`	Joint-limit braking distance in radians
`singularity_max_approach_rate`	`0.25`	Maximum singularity-ratio approach rate
`kinetic_energy_cost`	`2e-5`	Kinetic-energy regularization cost

Build from CLI args with register_ik_args + ik_params_from_args:

python your_ik_node.py --tick-hz 250 --limit-velocity

Without --config, --limit-velocity uses the built-in per-arm caps [2, 2, 3.14, 3.14, 6.3, 6.3, 6.3] rad/s. An optional YAML override uses a seven-entry arm_velocity_limits list:

arm_velocity_limits: [2.0, 2.0, 3.14, 3.14, 6.3, 6.3, 6.3]

python your_ik_node.py --limit-velocity --config ./ik_limits.yaml

Constrained IK behavior

A bare IKParams() instance enables four complementary mechanisms:

Frame-error bounding limits the Cartesian correction requested by one outer solve while retaining the full target for subsequent cycles. Position bounding activates smoothly with target linear speed and remains latched while accumulated position lag is significant; orientation bounding is always active when configured.
Nullspace posture regulation guides the redundant arm motion toward the initial home posture without applying a full joint-space posture objective.
Singularity approach limiting slows only motion that moves the arm toward a poorly conditioned configuration.
Kinetic-energy regularization provides a weak mass-matrix-based tie-breaker between kinematically similar solutions. It is not inverse dynamics or gravity compensation.

Frame-error bounding limits accumulated feedback correction, not target velocity, and does not replace joint velocity limits. The full-joint home PostureTask is a separate optional objective controlled by posture_cost and is disabled by default.

The bare library default leaves hardware-specific per-joint velocity limits opt-in: provide velocity_limits directly or use --limit-velocity. The CLI flag selects the built-in caps unless --config overrides them. Enabling these limits replaces the position-only arm limit with one recoverable position/velocity envelope, so a command already slightly outside a position bound can return over multiple feasible steps. Preventive braking then reduces only the velocity approaching a nearby position bound; it is enabled by default with velocity limits and can be disabled with --no-joint-braking.

These limits constrain the QP solution. A downstream driver may apply its own independently configured execution-layer velocity envelope; the two sets of caps are not required to match.

Set both frame-error limits to zero to remove frame-error bounding. Set nullspace_cost, singularity_max_approach_rate, or kinetic_energy_cost to zero to disable the corresponding mechanism. These are kinematic command-layer mechanisms, not a certified whole-robot safety controller.

The remaining curve-shape and threshold parameters are regular IKParams fields but are intentionally not exposed as CLI flags. Call update_measured_state() with fresh driver qpos for state-aware limits; the caller owns freshness and should call clear_measured_state() when that state expires.

License

Licensed under the Apache License 2.0. See LICENSE.txt for details.

Code of Conduct

All participation in the OpenArm project is governed by our Code of Conduct.

OpenArm Control

Reusable kinematics and control utilities for OpenArm, backed by MuJoCo and mink.

Install

uv sync

Usage

`Kinematics`

Poses are float32[7] = [px, py, pz, qw, qx, qy, qz], expressed in the scene's arm_origin site frame by default (--origin-frame world restores world-frame poses).

fromopenarm_controlimportKinematics, IKParams, ArmSetup# FK onlykin=Kinematics(setup)
pose=kin.fk("right", joints) # float32[7]pose_r, pose_l=kin.fk_bimanual(r, l) # single mj_forward# IKkin=Kinematics(setup, IKParams())
kin.set_target("right", pose_r)
kin.set_target("left", pose_l)
result=kin.solve() # float32[16] right[8]+left[8]

`IKParams`

Solver configuration passed to Kinematics. Key fields are listed below; all fields have defaults.

Field	Default	Description
`position_cost`	`12.0`	Position task weight
`orientation_cost`	`1.5`	Orientation task weight
`lm_damping`	`0.01`	Per-task Levenberg-Marquardt damping
`damping`	`0.1`	Global Tikhonov regularization
`solver`	`"daqp"`	QP backend
`posture_cost`	`0.0`	Full home posture task weight (0 = disabled)
`dt`	`0.004`	Outer control period, divided across IK iterations
`max_iters`	`5`	IK sub-iterations per solve
`velocity_limits`	`None`	Joint-name to velocity-cap mapping in rad/s; `None` keeps position-only limits
`frame_position_error_limit`	`0.02`	Total position-error request per outer IK solve
`frame_orientation_error_limit`	`0.25`	Total orientation-error request per outer IK solve
`nullspace_cost`	`8.5`	Fixed-home nullspace posture cost
`nullspace_return_rate`	`1.6`	Nullspace return rate in s⁻¹
`joint_braking`	`True`	Enable preventive braking when velocity limits are active
`joint_braking_distance`	`0.2`	Joint-limit braking distance in radians
`singularity_max_approach_rate`	`0.25`	Maximum singularity-ratio approach rate
`kinetic_energy_cost`	`2e-5`	Kinetic-energy regularization cost

Build from CLI args with register_ik_args + ik_params_from_args:

python your_ik_node.py --tick-hz 250 --limit-velocity

Without --config, --limit-velocity uses the built-in per-arm caps [2, 2, 3.14, 3.14, 6.3, 6.3, 6.3] rad/s. An optional YAML override uses a seven-entry arm_velocity_limits list:

arm_velocity_limits: [2.0, 2.0, 3.14, 3.14, 6.3, 6.3, 6.3]

python your_ik_node.py --limit-velocity --config ./ik_limits.yaml

Constrained IK behavior

A bare IKParams() instance enables four complementary mechanisms:

Frame-error bounding limits the Cartesian correction requested by one outer solve while retaining the full target for subsequent cycles. Position bounding activates smoothly with target linear speed and remains latched while accumulated position lag is significant; orientation bounding is always active when configured.
Nullspace posture regulation guides the redundant arm motion toward the initial home posture without applying a full joint-space posture objective.
Singularity approach limiting slows only motion that moves the arm toward a poorly conditioned configuration.
Kinetic-energy regularization provides a weak mass-matrix-based tie-breaker between kinematically similar solutions. It is not inverse dynamics or gravity compensation.

Frame-error bounding limits accumulated feedback correction, not target velocity, and does not replace joint velocity limits. The full-joint home PostureTask is a separate optional objective controlled by posture_cost and is disabled by default.

The bare library default leaves hardware-specific per-joint velocity limits opt-in: provide velocity_limits directly or use --limit-velocity. The CLI flag selects the built-in caps unless --config overrides them. Enabling these limits replaces the position-only arm limit with one recoverable position/velocity envelope, so a command already slightly outside a position bound can return over multiple feasible steps. Preventive braking then reduces only the velocity approaching a nearby position bound; it is enabled by default with velocity limits and can be disabled with --no-joint-braking.

These limits constrain the QP solution. A downstream driver may apply its own independently configured execution-layer velocity envelope; the two sets of caps are not required to match.

Set both frame-error limits to zero to remove frame-error bounding. Set nullspace_cost, singularity_max_approach_rate, or kinetic_energy_cost to zero to disable the corresponding mechanism. These are kinematic command-layer mechanisms, not a certified whole-robot safety controller.

The remaining curve-shape and threshold parameters are regular IKParams fields but are intentionally not exposed as CLI flags. Call update_measured_state() with fresh driver qpos for state-aware limits; the caller owns freshness and should call clear_measured_state() when that state expires.

License

Licensed under the Apache License 2.0. See LICENSE.txt for details.

Code of Conduct

All participation in the OpenArm project is governed by our Code of Conduct.

OpenArm Control

Reusable kinematics and control utilities for OpenArm, backed by MuJoCo and mink.

Install

uv sync

Usage

`Kinematics`

Poses are float32[7] = [px, py, pz, qw, qx, qy, qz], expressed in the scene's arm_origin site frame by default (--origin-frame world restores world-frame poses).

fromopenarm_controlimportKinematics, IKParams, ArmSetup# FK onlykin=Kinematics(setup)
pose=kin.fk("right", joints) # float32[7]pose_r, pose_l=kin.fk_bimanual(r, l) # single mj_forward# IKkin=Kinematics(setup, IKParams())
kin.set_target("right", pose_r)
kin.set_target("left", pose_l)
result=kin.solve() # float32[16] right[8]+left[8]

`IKParams`

Solver configuration passed to Kinematics. Key fields are listed below; all fields have defaults.

Field	Default	Description
`position_cost`	`12.0`	Position task weight
`orientation_cost`	`1.5`	Orientation task weight
`lm_damping`	`0.01`	Per-task Levenberg-Marquardt damping
`damping`	`0.1`	Global Tikhonov regularization
`solver`	`"daqp"`	QP backend
`posture_cost`	`0.0`	Full home posture task weight (0 = disabled)
`dt`	`0.004`	Outer control period, divided across IK iterations
`max_iters`	`5`	IK sub-iterations per solve
`velocity_limits`	`None`	Joint-name to velocity-cap mapping in rad/s; `None` keeps position-only limits
`frame_position_error_limit`	`0.02`	Total position-error request per outer IK solve
`frame_orientation_error_limit`	`0.25`	Total orientation-error request per outer IK solve
`nullspace_cost`	`8.5`	Fixed-home nullspace posture cost
`nullspace_return_rate`	`1.6`	Nullspace return rate in s⁻¹
`joint_braking`	`True`	Enable preventive braking when velocity limits are active
`joint_braking_distance`	`0.2`	Joint-limit braking distance in radians
`singularity_max_approach_rate`	`0.25`	Maximum singularity-ratio approach rate
`kinetic_energy_cost`	`2e-5`	Kinetic-energy regularization cost

Build from CLI args with register_ik_args + ik_params_from_args:

python your_ik_node.py --tick-hz 250 --limit-velocity

Without --config, --limit-velocity uses the built-in per-arm caps [2, 2, 3.14, 3.14, 6.3, 6.3, 6.3] rad/s. An optional YAML override uses a seven-entry arm_velocity_limits list:

arm_velocity_limits: [2.0, 2.0, 3.14, 3.14, 6.3, 6.3, 6.3]

python your_ik_node.py --limit-velocity --config ./ik_limits.yaml

Constrained IK behavior

A bare IKParams() instance enables four complementary mechanisms:

Frame-error bounding limits the Cartesian correction requested by one outer solve while retaining the full target for subsequent cycles. Position bounding activates smoothly with target linear speed and remains latched while accumulated position lag is significant; orientation bounding is always active when configured.
Nullspace posture regulation guides the redundant arm motion toward the initial home posture without applying a full joint-space posture objective.
Singularity approach limiting slows only motion that moves the arm toward a poorly conditioned configuration.
Kinetic-energy regularization provides a weak mass-matrix-based tie-breaker between kinematically similar solutions. It is not inverse dynamics or gravity compensation.

Frame-error bounding limits accumulated feedback correction, not target velocity, and does not replace joint velocity limits. The full-joint home PostureTask is a separate optional objective controlled by posture_cost and is disabled by default.

The bare library default leaves hardware-specific per-joint velocity limits opt-in: provide velocity_limits directly or use --limit-velocity. The CLI flag selects the built-in caps unless --config overrides them. Enabling these limits replaces the position-only arm limit with one recoverable position/velocity envelope, so a command already slightly outside a position bound can return over multiple feasible steps. Preventive braking then reduces only the velocity approaching a nearby position bound; it is enabled by default with velocity limits and can be disabled with --no-joint-braking.

These limits constrain the QP solution. A downstream driver may apply its own independently configured execution-layer velocity envelope; the two sets of caps are not required to match.

Set both frame-error limits to zero to remove frame-error bounding. Set nullspace_cost, singularity_max_approach_rate, or kinetic_energy_cost to zero to disable the corresponding mechanism. These are kinematic command-layer mechanisms, not a certified whole-robot safety controller.

The remaining curve-shape and threshold parameters are regular IKParams fields but are intentionally not exposed as CLI flags. Call update_measured_state() with fresh driver qpos for state-aware limits; the caller owns freshness and should call clear_measured_state() when that state expires.

License

Licensed under the Apache License 2.0. See LICENSE.txt for details.

Code of Conduct

All participation in the OpenArm project is governed by our Code of Conduct.

OpenArm Control

Reusable kinematics and control utilities for OpenArm, backed by MuJoCo and mink.

Install

uv sync

Usage

`Kinematics`

Poses are float32[7] = [px, py, pz, qw, qx, qy, qz], expressed in the scene's arm_origin site frame by default (--origin-frame world restores world-frame poses).

fromopenarm_controlimportKinematics, IKParams, ArmSetup# FK onlykin=Kinematics(setup)
pose=kin.fk("right", joints) # float32[7]pose_r, pose_l=kin.fk_bimanual(r, l) # single mj_forward# IKkin=Kinematics(setup, IKParams())
kin.set_target("right", pose_r)
kin.set_target("left", pose_l)
result=kin.solve() # float32[16] right[8]+left[8]

`IKParams`

Solver configuration passed to Kinematics. Key fields are listed below; all fields have defaults.

Field	Default	Description
`position_cost`	`12.0`	Position task weight
`orientation_cost`	`1.5`	Orientation task weight
`lm_damping`	`0.01`	Per-task Levenberg-Marquardt damping
`damping`	`0.1`	Global Tikhonov regularization
`solver`	`"daqp"`	QP backend
`posture_cost`	`0.0`	Full home posture task weight (0 = disabled)
`dt`	`0.004`	Outer control period, divided across IK iterations
`max_iters`	`5`	IK sub-iterations per solve
`velocity_limits`	`None`	Joint-name to velocity-cap mapping in rad/s; `None` keeps position-only limits
`frame_position_error_limit`	`0.02`	Total position-error request per outer IK solve
`frame_orientation_error_limit`	`0.25`	Total orientation-error request per outer IK solve
`nullspace_cost`	`8.5`	Fixed-home nullspace posture cost
`nullspace_return_rate`	`1.6`	Nullspace return rate in s⁻¹
`joint_braking`	`True`	Enable preventive braking when velocity limits are active
`joint_braking_distance`	`0.2`	Joint-limit braking distance in radians
`singularity_max_approach_rate`	`0.25`	Maximum singularity-ratio approach rate
`kinetic_energy_cost`	`2e-5`	Kinetic-energy regularization cost

Build from CLI args with register_ik_args + ik_params_from_args:

python your_ik_node.py --tick-hz 250 --limit-velocity

Without --config, --limit-velocity uses the built-in per-arm caps [2, 2, 3.14, 3.14, 6.3, 6.3, 6.3] rad/s. An optional YAML override uses a seven-entry arm_velocity_limits list:

arm_velocity_limits: [2.0, 2.0, 3.14, 3.14, 6.3, 6.3, 6.3]

python your_ik_node.py --limit-velocity --config ./ik_limits.yaml

Constrained IK behavior

A bare IKParams() instance enables four complementary mechanisms:

Frame-error bounding limits the Cartesian correction requested by one outer solve while retaining the full target for subsequent cycles. Position bounding activates smoothly with target linear speed and remains latched while accumulated position lag is significant; orientation bounding is always active when configured.
Nullspace posture regulation guides the redundant arm motion toward the initial home posture without applying a full joint-space posture objective.
Singularity approach limiting slows only motion that moves the arm toward a poorly conditioned configuration.
Kinetic-energy regularization provides a weak mass-matrix-based tie-breaker between kinematically similar solutions. It is not inverse dynamics or gravity compensation.

Frame-error bounding limits accumulated feedback correction, not target velocity, and does not replace joint velocity limits. The full-joint home PostureTask is a separate optional objective controlled by posture_cost and is disabled by default.

The bare library default leaves hardware-specific per-joint velocity limits opt-in: provide velocity_limits directly or use --limit-velocity. The CLI flag selects the built-in caps unless --config overrides them. Enabling these limits replaces the position-only arm limit with one recoverable position/velocity envelope, so a command already slightly outside a position bound can return over multiple feasible steps. Preventive braking then reduces only the velocity approaching a nearby position bound; it is enabled by default with velocity limits and can be disabled with --no-joint-braking.

These limits constrain the QP solution. A downstream driver may apply its own independently configured execution-layer velocity envelope; the two sets of caps are not required to match.

Set both frame-error limits to zero to remove frame-error bounding. Set nullspace_cost, singularity_max_approach_rate, or kinetic_energy_cost to zero to disable the corresponding mechanism. These are kinematic command-layer mechanisms, not a certified whole-robot safety controller.

The remaining curve-shape and threshold parameters are regular IKParams fields but are intentionally not exposed as CLI flags. Call update_measured_state() with fresh driver qpos for state-aware limits; the caller owns freshness and should call clear_measured_state() when that state expires.

License

Licensed under the Apache License 2.0. See LICENSE.txt for details.

Code of Conduct

All participation in the OpenArm project is governed by our Code of Conduct.

OpenArm Control

Reusable kinematics and control utilities for OpenArm, backed by MuJoCo and mink.

Install

uv sync

Usage

`Kinematics`

Poses are float32[7] = [px, py, pz, qw, qx, qy, qz], expressed in the scene's arm_origin site frame by default (--origin-frame world restores world-frame poses).

fromopenarm_controlimportKinematics, IKParams, ArmSetup# FK onlykin=Kinematics(setup)
pose=kin.fk("right", joints) # float32[7]pose_r, pose_l=kin.fk_bimanual(r, l) # single mj_forward# IKkin=Kinematics(setup, IKParams())
kin.set_target("right", pose_r)
kin.set_target("left", pose_l)
result=kin.solve() # float32[16] right[8]+left[8]

`IKParams`

Solver configuration passed to Kinematics. Key fields are listed below; all fields have defaults.

Field	Default	Description
`position_cost`	`12.0`	Position task weight
`orientation_cost`	`1.5`	Orientation task weight
`lm_damping`	`0.01`	Per-task Levenberg-Marquardt damping
`damping`	`0.1`	Global Tikhonov regularization
`solver`	`"daqp"`	QP backend
`posture_cost`	`0.0`	Full home posture task weight (0 = disabled)
`dt`	`0.004`	Outer control period, divided across IK iterations
`max_iters`	`5`	IK sub-iterations per solve
`velocity_limits`	`None`	Joint-name to velocity-cap mapping in rad/s; `None` keeps position-only limits
`frame_position_error_limit`	`0.02`	Total position-error request per outer IK solve
`frame_orientation_error_limit`	`0.25`	Total orientation-error request per outer IK solve
`nullspace_cost`	`8.5`	Fixed-home nullspace posture cost
`nullspace_return_rate`	`1.6`	Nullspace return rate in s⁻¹
`joint_braking`	`True`	Enable preventive braking when velocity limits are active
`joint_braking_distance`	`0.2`	Joint-limit braking distance in radians
`singularity_max_approach_rate`	`0.25`	Maximum singularity-ratio approach rate
`kinetic_energy_cost`	`2e-5`	Kinetic-energy regularization cost

Build from CLI args with register_ik_args + ik_params_from_args:

python your_ik_node.py --tick-hz 250 --limit-velocity

Without --config, --limit-velocity uses the built-in per-arm caps [2, 2, 3.14, 3.14, 6.3, 6.3, 6.3] rad/s. An optional YAML override uses a seven-entry arm_velocity_limits list:

arm_velocity_limits: [2.0, 2.0, 3.14, 3.14, 6.3, 6.3, 6.3]

python your_ik_node.py --limit-velocity --config ./ik_limits.yaml

Constrained IK behavior

A bare IKParams() instance enables four complementary mechanisms:

Frame-error bounding limits the Cartesian correction requested by one outer solve while retaining the full target for subsequent cycles. Position bounding activates smoothly with target linear speed and remains latched while accumulated position lag is significant; orientation bounding is always active when configured.
Nullspace posture regulation guides the redundant arm motion toward the initial home posture without applying a full joint-space posture objective.
Singularity approach limiting slows only motion that moves the arm toward a poorly conditioned configuration.
Kinetic-energy regularization provides a weak mass-matrix-based tie-breaker between kinematically similar solutions. It is not inverse dynamics or gravity compensation.

Frame-error bounding limits accumulated feedback correction, not target velocity, and does not replace joint velocity limits. The full-joint home PostureTask is a separate optional objective controlled by posture_cost and is disabled by default.

The bare library default leaves hardware-specific per-joint velocity limits opt-in: provide velocity_limits directly or use --limit-velocity. The CLI flag selects the built-in caps unless --config overrides them. Enabling these limits replaces the position-only arm limit with one recoverable position/velocity envelope, so a command already slightly outside a position bound can return over multiple feasible steps. Preventive braking then reduces only the velocity approaching a nearby position bound; it is enabled by default with velocity limits and can be disabled with --no-joint-braking.

These limits constrain the QP solution. A downstream driver may apply its own independently configured execution-layer velocity envelope; the two sets of caps are not required to match.

Set both frame-error limits to zero to remove frame-error bounding. Set nullspace_cost, singularity_max_approach_rate, or kinetic_energy_cost to zero to disable the corresponding mechanism. These are kinematic command-layer mechanisms, not a certified whole-robot safety controller.

The remaining curve-shape and threshold parameters are regular IKParams fields but are intentionally not exposed as CLI flags. Call update_measured_state() with fresh driver qpos for state-aware limits; the caller owns freshness and should call clear_measured_state() when that state expires.

License

Licensed under the Apache License 2.0. See LICENSE.txt for details.

Code of Conduct

All participation in the OpenArm project is governed by our Code of Conduct.

OpenArm Control

Reusable kinematics and control utilities for OpenArm, backed by MuJoCo and mink.

Install

uv sync

Usage

`Kinematics`

Poses are float32[7] = [px, py, pz, qw, qx, qy, qz], expressed in the scene's arm_origin site frame by default (--origin-frame world restores world-frame poses).

fromopenarm_controlimportKinematics, IKParams, ArmSetup# FK onlykin=Kinematics(setup)
pose=kin.fk("right", joints) # float32[7]pose_r, pose_l=kin.fk_bimanual(r, l) # single mj_forward# IKkin=Kinematics(setup, IKParams())
kin.set_target("right", pose_r)
kin.set_target("left", pose_l)
result=kin.solve() # float32[16] right[8]+left[8]

`IKParams`

Solver configuration passed to Kinematics. Key fields are listed below; all fields have defaults.

Field	Default	Description
`position_cost`	`12.0`	Position task weight
`orientation_cost`	`1.5`	Orientation task weight
`lm_damping`	`0.01`	Per-task Levenberg-Marquardt damping
`damping`	`0.1`	Global Tikhonov regularization
`solver`	`"daqp"`	QP backend
`posture_cost`	`0.0`	Full home posture task weight (0 = disabled)
`dt`	`0.004`	Outer control period, divided across IK iterations
`max_iters`	`5`	IK sub-iterations per solve
`velocity_limits`	`None`	Joint-name to velocity-cap mapping in rad/s; `None` keeps position-only limits
`frame_position_error_limit`	`0.02`	Total position-error request per outer IK solve
`frame_orientation_error_limit`	`0.25`	Total orientation-error request per outer IK solve
`nullspace_cost`	`8.5`	Fixed-home nullspace posture cost
`nullspace_return_rate`	`1.6`	Nullspace return rate in s⁻¹
`joint_braking`	`True`	Enable preventive braking when velocity limits are active
`joint_braking_distance`	`0.2`	Joint-limit braking distance in radians
`singularity_max_approach_rate`	`0.25`	Maximum singularity-ratio approach rate
`kinetic_energy_cost`	`2e-5`	Kinetic-energy regularization cost

Build from CLI args with register_ik_args + ik_params_from_args:

python your_ik_node.py --tick-hz 250 --limit-velocity

Without --config, --limit-velocity uses the built-in per-arm caps [2, 2, 3.14, 3.14, 6.3, 6.3, 6.3] rad/s. An optional YAML override uses a seven-entry arm_velocity_limits list:

arm_velocity_limits: [2.0, 2.0, 3.14, 3.14, 6.3, 6.3, 6.3]

python your_ik_node.py --limit-velocity --config ./ik_limits.yaml

Constrained IK behavior

A bare IKParams() instance enables four complementary mechanisms:

Frame-error bounding limits the Cartesian correction requested by one outer solve while retaining the full target for subsequent cycles. Position bounding activates smoothly with target linear speed and remains latched while accumulated position lag is significant; orientation bounding is always active when configured.
Nullspace posture regulation guides the redundant arm motion toward the initial home posture without applying a full joint-space posture objective.
Singularity approach limiting slows only motion that moves the arm toward a poorly conditioned configuration.
Kinetic-energy regularization provides a weak mass-matrix-based tie-breaker between kinematically similar solutions. It is not inverse dynamics or gravity compensation.

Frame-error bounding limits accumulated feedback correction, not target velocity, and does not replace joint velocity limits. The full-joint home PostureTask is a separate optional objective controlled by posture_cost and is disabled by default.

The bare library default leaves hardware-specific per-joint velocity limits opt-in: provide velocity_limits directly or use --limit-velocity. The CLI flag selects the built-in caps unless --config overrides them. Enabling these limits replaces the position-only arm limit with one recoverable position/velocity envelope, so a command already slightly outside a position bound can return over multiple feasible steps. Preventive braking then reduces only the velocity approaching a nearby position bound; it is enabled by default with velocity limits and can be disabled with --no-joint-braking.

These limits constrain the QP solution. A downstream driver may apply its own independently configured execution-layer velocity envelope; the two sets of caps are not required to match.

Set both frame-error limits to zero to remove frame-error bounding. Set nullspace_cost, singularity_max_approach_rate, or kinetic_energy_cost to zero to disable the corresponding mechanism. These are kinematic command-layer mechanisms, not a certified whole-robot safety controller.

The remaining curve-shape and threshold parameters are regular IKParams fields but are intentionally not exposed as CLI flags. Call update_measured_state() with fresh driver qpos for state-aware limits; the caller owns freshness and should call clear_measured_state() when that state expires.

License

Licensed under the Apache License 2.0. See LICENSE.txt for details.

Code of Conduct

All participation in the OpenArm project is governed by our Code of Conduct.

OpenArm Control

Reusable kinematics and control utilities for OpenArm, backed by MuJoCo and mink.

Install

uv sync

Usage

`Kinematics`

Poses are float32[7] = [px, py, pz, qw, qx, qy, qz], expressed in the scene's arm_origin site frame by default (--origin-frame world restores world-frame poses).

fromopenarm_controlimportKinematics, IKParams, ArmSetup# FK onlykin=Kinematics(setup)
pose=kin.fk("right", joints) # float32[7]pose_r, pose_l=kin.fk_bimanual(r, l) # single mj_forward# IKkin=Kinematics(setup, IKParams())
kin.set_target("right", pose_r)
kin.set_target("left", pose_l)
result=kin.solve() # float32[16] right[8]+left[8]

`IKParams`

Solver configuration passed to Kinematics. Key fields are listed below; all fields have defaults.

Field	Default	Description
`position_cost`	`12.0`	Position task weight
`orientation_cost`	`1.5`	Orientation task weight
`lm_damping`	`0.01`	Per-task Levenberg-Marquardt damping
`damping`	`0.1`	Global Tikhonov regularization
`solver`	`"daqp"`	QP backend
`posture_cost`	`0.0`	Full home posture task weight (0 = disabled)
`dt`	`0.004`	Outer control period, divided across IK iterations
`max_iters`	`5`	IK sub-iterations per solve
`velocity_limits`	`None`	Joint-name to velocity-cap mapping in rad/s; `None` keeps position-only limits
`frame_position_error_limit`	`0.02`	Total position-error request per outer IK solve
`frame_orientation_error_limit`	`0.25`	Total orientation-error request per outer IK solve
`nullspace_cost`	`8.5`	Fixed-home nullspace posture cost
`nullspace_return_rate`	`1.6`	Nullspace return rate in s⁻¹
`joint_braking`	`True`	Enable preventive braking when velocity limits are active
`joint_braking_distance`	`0.2`	Joint-limit braking distance in radians
`singularity_max_approach_rate`	`0.25`	Maximum singularity-ratio approach rate
`kinetic_energy_cost`	`2e-5`	Kinetic-energy regularization cost

Build from CLI args with register_ik_args + ik_params_from_args:

python your_ik_node.py --tick-hz 250 --limit-velocity

Without --config, --limit-velocity uses the built-in per-arm caps [2, 2, 3.14, 3.14, 6.3, 6.3, 6.3] rad/s. An optional YAML override uses a seven-entry arm_velocity_limits list:

arm_velocity_limits: [2.0, 2.0, 3.14, 3.14, 6.3, 6.3, 6.3]

python your_ik_node.py --limit-velocity --config ./ik_limits.yaml

Constrained IK behavior

A bare IKParams() instance enables four complementary mechanisms:

Frame-error bounding limits the Cartesian correction requested by one outer solve while retaining the full target for subsequent cycles. Position bounding activates smoothly with target linear speed and remains latched while accumulated position lag is significant; orientation bounding is always active when configured.
Nullspace posture regulation guides the redundant arm motion toward the initial home posture without applying a full joint-space posture objective.
Singularity approach limiting slows only motion that moves the arm toward a poorly conditioned configuration.
Kinetic-energy regularization provides a weak mass-matrix-based tie-breaker between kinematically similar solutions. It is not inverse dynamics or gravity compensation.

Frame-error bounding limits accumulated feedback correction, not target velocity, and does not replace joint velocity limits. The full-joint home PostureTask is a separate optional objective controlled by posture_cost and is disabled by default.

The bare library default leaves hardware-specific per-joint velocity limits opt-in: provide velocity_limits directly or use --limit-velocity. The CLI flag selects the built-in caps unless --config overrides them. Enabling these limits replaces the position-only arm limit with one recoverable position/velocity envelope, so a command already slightly outside a position bound can return over multiple feasible steps. Preventive braking then reduces only the velocity approaching a nearby position bound; it is enabled by default with velocity limits and can be disabled with --no-joint-braking.

These limits constrain the QP solution. A downstream driver may apply its own independently configured execution-layer velocity envelope; the two sets of caps are not required to match.

Set both frame-error limits to zero to remove frame-error bounding. Set nullspace_cost, singularity_max_approach_rate, or kinetic_energy_cost to zero to disable the corresponding mechanism. These are kinematic command-layer mechanisms, not a certified whole-robot safety controller.

The remaining curve-shape and threshold parameters are regular IKParams fields but are intentionally not exposed as CLI flags. Call update_measured_state() with fresh driver qpos for state-aware limits; the caller owns freshness and should call clear_measured_state() when that state expires.

License

Licensed under the Apache License 2.0. See LICENSE.txt for details.

Code of Conduct

All participation in the OpenArm project is governed by our Code of Conduct.

Name		Name	Last commit message	Last commit date
.github		.github
dev		dev
src/openarm_control		src/openarm_control
tests		tests
.editorconfig		.editorconfig
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE.txt		LICENSE.txt
README.md		README.md
pyproject.toml		pyproject.toml

Name		Name	Last commit message	Last commit date
.github		.github
dev		dev
src/openarm_control		src/openarm_control
tests		tests
.editorconfig		.editorconfig
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE.txt		LICENSE.txt
README.md		README.md
pyproject.toml		pyproject.toml

Name		Name	Last commit message	Last commit date
.github		.github
dev		dev
src/openarm_control		src/openarm_control
tests		tests
.editorconfig		.editorconfig
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE.txt		LICENSE.txt
README.md		README.md
pyproject.toml		pyproject.toml

Name		Name	Last commit message	Last commit date
.github		.github
dev		dev
src/openarm_control		src/openarm_control
tests		tests
.editorconfig		.editorconfig
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE.txt		LICENSE.txt
README.md		README.md
pyproject.toml		pyproject.toml

Name		Name	Last commit message	Last commit date
.github		.github
dev		dev
src/openarm_control		src/openarm_control
tests		tests
.editorconfig		.editorconfig
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE.txt		LICENSE.txt
README.md		README.md
pyproject.toml		pyproject.toml

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

OpenArm Control

Install

Usage

Kinematics

IKParams

Constrained IK behavior

Related links

License

Code of Conduct

About

Resources

Code of conduct

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

OpenArm Control

Install

Usage

Kinematics

IKParams

Constrained IK behavior

Related links

License

Code of Conduct

About

Resources

Code of conduct

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

OpenArm Control

Install

Usage

Kinematics

IKParams

Constrained IK behavior

Related links

License

Code of Conduct

About

Resources

Code of conduct

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

`Kinematics`

`IKParams`

`Kinematics`

`IKParams`

`Kinematics`

`IKParams`

`Kinematics`

`IKParams`

`Kinematics`

`IKParams`

`Kinematics`