Fix V1 model frames, inertias and gripper limits by stevenaya · Pull Request #79 · enactic/openarm_description

stevenaya · 2026-10-11T22:56:47Z

The V1 parallel gripper has inconsistent joint/mesh origins, invalid finger inertia tensors and inconsistent component mass assignments. Correct the gripper frames and collision geometry using openarm_mujoco#82, organize the end effector as link7 → hand → fingers / TCP, and recalculate link7, hand and finger masses, COMs and inertias from measured assemblies and CAD. Use the same end-effector parameters in single-arm, bimanual and standalone models. Set the parallel-gripper joint limits to 150.75 N and 0.661 m/s using the V1 linkage geometry and DM4310 specifications.

Split PRs

This Draft PR tracks the complete V1 changes. Each split PR covers one functional change; dependent model updates are validated with their prerequisites.

#81: remove the stray Cube from the V1 link0 visual mesh; merged.
#80 (Draft): use the right arm convention for the default V1 single arm.

The example URDF update #82 and prefix fix #83 are ready for review. Remaining splits follow this order:

Order	Scope	Dependency / review point
1	Regenerate the stale V1 example URDF from main	Establish a generated-file baseline for later model changes.
2	Fix V1 prefix and naming references	Cover gripper attachment, body mounting, mimic and ROS2 control names.
3	Read shared gripper limits and set 150.75 N / 0.661 m/s	Keep the configuration wiring and unit-correct limits together.
4	Correct finger products of inertia	Zero the invalid cross terms while retaining masses, COMs and diagonal terms.
5	Reuse the robot gripper macro in the standalone entry	Follow the prefix and shared-limit fixes; keep physical parameter changes in their respective PRs.
6	Attach fingers to hand and correct gripper origins	Use `link7 → hand → fingers / TCP`, with hand Z=100.1 mm and finger origins=(0, ±5, 15) mm in hand. Convert mesh/COM offsets together; preserve the existing 186 mm TCP until split 8.
7	Rotate the opposing finger mesh and keep link axes aligned	Follow split 6; update visual/collision rotation and COM in the same frame.
8	Move the default TCP to 193.1 mm from link7	Follow splits 5/6; use a 93 mm hand-local offset in the shared macro and standalone entry. Keep the dispatcher's main-branch TCP behavior.
9	Recalculate link7, hand and finger inertias	Follow split 7; update mass, COM and tensor together from measured assemblies and CAD, including the half-rod allocation and mirrored link7 symmetry.
10	Update the hand collision mesh	Follow the frame correction and coordinate with the existing #65.
11	Update the finger collision mesh	Follow the frame/mesh orientation fixes; assess the 64,440-triangle collider's runtime cost.
12	Update V1/V2 pedestal mass, COM and diagonal inertia	Use the measured 3.55 kg metal base plus approximately 190 g cover; retain the CAD-derived COM and diagonal terms.

Regenerate the example URDF with each subsequent model change. Frame conversions keep geometry and inertial coordinates together. The broader component-directory refactor and dispatcher TCP-override support remain separate follow-ups.

Changes

Treat empty arm_prefix like right_ with reflect=+1. The default single arm uses unmirrored arm meshes, right-arm COM/inertia expressions and J7 axis +Y. Joint names, origins and limits retain the single-arm convention, including J2 at −100° to +100°.
Use link7 → hand → fingers / hand_tcp. Place hand 100.1 mm from link7 and finger origins at (0, ±5, 15) mm in the hand frame, or (0, ±5, 115.1) mm relative to link7. Adopt the Isaac Lab TCP reference at (0, 0, 0.1931) m relative to link7, moving it forward from description's 186 mm reference. Use a 93 mm hand-local TCP offset (193.1 − 100.1) for single-arm, bimanual and standalone configurations, with TCP axes aligned to link7.
Keep both finger link frames aligned with hand. Rotate the opposing finger mesh by 180° about Z through its visual/collision origins, and express its mesh offset and COM in the unrotated link frame. Use finger_joint1 axis 0 -1 0 and finger_joint2 axis 0 1 0, with mimic multiplier +1. Both fingers reuse one positively scaled mesh.
Recalculate link7, hand and both fingers as a coordinated mass/COM/inertia update: 405.497127 g, 172.311174 g and 74.449987 g per finger. Use the CAD component allocation and measured masses below; apply the link7 X-symmetry approximation and the correct left-arm reflection.
Replace the legacy pedestal mass properties in V1 and V2 with 3.74 kg, COM (−0.016206894902, 0, 0.244091987626) m, and CAD-derived diagonal inertia (0.248946829107, 0.253033907704, 0.0140271775534) kg·m². Set all three cross terms to zero and retain the full base collision STL.
Copy hand and finger collision STL assets from MuJoCo, covering the hand rail and rounded ends and correcting the finger collision shape. Remove the accidentally exported Blender Cube from link0.dae.
Make the standalone parallel gripper call the same gripper macro as the complete robot, with base_link as its mounting frame. The standalone entry forwards its TCP arguments directly to the shared macro. Set TCP defaults in the shared macro and standalone entry, and share the configured joint limits.
Set the shared parallel-gripper limits to effort: 150.75 and velocity: 0.661 for single-arm, bimanual and standalone configurations, and regenerate the example URDF.
Fix no_prefix references in gripper attachment, body mounting and single-arm ROS2 control joint names. Regenerate the V1 bimanual example URDF.

Measured end-effector allocation

Source: openarm_hardware 1.0.1, STEP/OpenArm01_follower.step, calibrated with the measured assemblies below.

Measurement	Mass	Boundary
L-bracket assembly, J8_A + J8_B	94 g	Includes internal assembly screws; both motor attachment screw sets are removed.
Rail support	64 g	Weighed separately.
Rail	48 g	Included in the 181 g group.
Rail, rotor/crank, rods, bearings and sliders	181 g	Includes internal hardware; excludes the support, support-to-rail screws, plastic jaws, jaw screws, motor and removed motor attachment screws.
Assembled gripper	312 g	Includes the support, support-to-rail screws, plastic jaws and jaw screws.

The motor uses its 300 g nominal mass. CAD fasteners add 20.708274 g outside the 94 g and 312 g weighed assemblies. The complete end assembly is therefore 726.708274 g. The four support-to-rail screws contribute a CAD estimate of 3.031322 g inside the 312 g measurement, leaving 63.968678 g for the plastic jaws and their mounting screws.

Body	Mass	Allocated components
`link7`	0.405497127 kg	Gripper motor, L-bracket assembly and its motor mounting screws.
`hand`	0.172311174 kg	Support, rail, fixed mounting screws, rotor/crank, rotor-side bearings/bolts and half of each rod.
Each finger	0.074449987 kg	Slider, aluminum adapter, plastic jaw, their hardware, finger-side bearing/bolt and half of its rod.

CAD geometry supplies each part's COM and central inertia. Measured masses calibrate the part groups; the slider mass is fitted to the remaining measured mass. Transform each tensor into its receiving link frame, then combine it with the parallel-axis theorem. At 22 mm travel per finger, split each rod's mass and central inertia equally between hand and its finger, retaining the rod's CAD COM for both contributions. This preserves the assembly's spatial inertia at the reference opening while approximating the rod motion over the stroke.

Inertia entries below are about each body's COM, expressed in its link axes. The order is (Ixx, Iyy, Izz, Ixy, Ixz, Iyz), in kg·m².

Body	COM (m)	Inertia (kg·m²)
Right `link7`	`(-0.000098974547, 0.003372444724, 0.061389197292)`	`(3.63783092067e-4, 3.35119095023e-4, 1.86511272319e-4, 0, 0, 7.09488421932e-5)`
`hand`	`(0, 0, 0.005122940872)`	`(2.50930641371e-4, 5.56062761675e-5, 2.90609333842e-4, 1.18380219510e-5, 0, 0)`
+Y `left_finger`	`(-0.004646697332, 0.012178906515, 0.013352894473)`	`(3.28426861725e-5, 4.17523619255e-5, 1.88211631821e-5, -4.81353477950e-7, -4.11024098296e-6, 3.50430778680e-6)`
−Y `right_finger`	`(0.004646697332, -0.012178906515, 0.013352894473)`	`(3.28426861725e-5, 4.17523619255e-5, 1.88211631821e-5, -4.81353477950e-7, 4.11024098296e-6, -3.50430778680e-6)`

Apply COM-centered X-symmetry to link7: I_sym = (I + Sx I Sx)/2, Sx = diag(-1, 1, 1). This sets Ixy = Ixz = 0, retaining its mass, COM, diagonal terms and Iyz. The tensor changes by 0.0893% in Frobenius norm and removes the small CAD asymmetry that tilted the displayed inertia box horizontally. Mirror the left link7 with Sy = diag(1, -1, 1); the hand and finger assembly uses the same orientation on both arms.

Pedestal mass properties

V1 and V2 use the same pedestal STL. The measured metal base is 3.55 kg, excluding the arm assemblies, their link0 attachment screws and the plastic chest cover. The cover weighs approximately 190 g, giving 3.74 kg for body_link0.

Integrate the public V1 STEP solids, apply their assembly transforms and combine their central inertias with the parallel-axis theorem. The metal assembly's CAD/material estimate is 3.667916108 kg; scale its mass and tensor by 3.55 / 3.667916108. Add the cover at 0.190 kg using its CAD mass distribution. Keep the resulting COM and diagonal terms, and set Ixy = Ixz = Iyz = 0 in the body-link axes.

The body link remains in the URDF tree. Update both versions' configuration files and the body inertial blocks in their example URDFs.

Parallel gripper joint limits

finger_joint is prismatic: effort is in N and velocity is in m/s. Let q be one finger's travel, so the total jaw opening is 2q.

The complete-robot macro previously hardcoded effort=333 and velocity=10, while the standalone gripper read YAML values effort=9 and velocity=20.943946. Both now read finger_joint.limit from the shared YAML, including lower/upper bounds. The table below compares the previous complete-robot values with the unified values.

The V1 CAD linkage gives J = |dq/dθ| between 0.0315659627 and 0.0464337254 m/rad over the 44 mm finger stroke. The minimum occurs at closure; the maximum occurs at a total opening of 50.4571 mm. Using the DM4310's 7 N·m peak torque and 200 rpm no-load maximum speed:

Joint limit	Previous	Calculation	Updated
`effort`	333 N	`7 / Jmax = 150.752496 N`	150.75 N
`velocity`	10 m/s	`Jmin × 200 × 2π / 60 = 0.661115976 m/s`	0.661 m/s

The force limit uses the single active opening coordinate, with the other finger following through mimic, and matches openarm_mujoco#87. Torque and speed values describe separate peak-torque and no-load operating points. The existing linear position mapping in the ROS2 hardware interface is unchanged.

Open items

ROS2 gripper homing units: openarm_ros2::return_to_zero() sends the 0.044 m gripper joint target directly as 0.044 rad. Both the initial command and the loop commands need joint_to_motor_radians(), producing −1.0472 rad for the existing 44 mm open target. The correction is prepared locally in openarm_ros2 for the later PR split.
Gripper dynamics: validate the half-rod approximation against measured motion across the opening range. The 300 g motor mass is nominal; screw and slider masses use the CAD allocation. #77's clarification discusses the motor's inclusion in link7.
Runtime validation: check hardware dynamics, Isaac Sim stepping and MoveIt/OctoMap self-filtering, including the runtime cost of the 64,440-triangle finger collider.
Component-directory and model-layout refactors are planned for a later PR; the standalone/shared-macro organization follows the existing V2 approach.

Validation

Base update validated on 0f60e8f2; end-effector allocation was validated on bd269c85.

The umbrella and six affected split branches each pass all eight single/bimanual × prefix × ROS2-control combinations, standalone generation and an explicit TCP override. The V1 example matches fresh Xacro output. All five V2 presets expand successfully; their only change is the pedestal inertia where the preset includes a body.
The final base, link7, hand and finger tensors pass positive-definiteness and triangle-inequality checks. Left/right reflections and the shared hand/finger parameters agree.
Fresh single-arm and bimanual URDFs agree with MuJoCo at 103 poses each on shared arm-body/COM poses, mass matrices and gravity/Coriolis bias. This rigid-body comparison omits meshes and motor armature.
Reparenting is checked separately against the previous opposing-finger and finger-collision branches at 103 poses each: body/COM poses and rigid-body dynamics are preserved.
Default TCP is (0, 0, 0.1931) m relative to link7, with aligned axes. Joint limits are effort=150.75 N and velocity=0.661 m/s.
The new base parameters pass 8 V1 umbrella configurations, 4 V1 base-branch configurations and all 5 V2 presets on both branches. A 103-pose comparison with MuJoCo's world-mounted pedestal preserves shared arm-body/COM poses, mass matrices and gravity/Coriolis terms.
check_urdf and git diff --check pass.