tron2-robot-description / CONTRIBUTING.md
LimX-Gwen's picture
Mirror tron2-robot-description from GitHub
493ea97 verified
|
Raw History Blame Contribute Delete
6.65 kB

Contributing to robot-description

Thanks for helping improve the TRON2 robot description. This repository holds URDF / xacro sources, MuJoCo XML, STL meshes, and USD assets. The guidelines below aim to keep the description consistent across simulators (Gazebo, MuJoCo, Isaac Sim) and downstream stacks.

Table of contents

Ways to contribute

  • Bug reports for URDF / xacro / MuJoCo XML inconsistencies.
  • Mesh simplification, collision cleanup, inertia corrections.
  • Documentation, verification snippets, sim integration examples.
  • New robot variants under tron2/<VARIANT>/ β€” see Adding a new robot variant.

We do not accept:

  • Vendor CAD files that are not licensed for re-distribution.
  • Calibration values, firmware, control policies, or model weights.
  • Images or media that disclose office locations, individuals, or non-public products.

Development setup

Prerequisites:

  • ROS 1 (Noetic) or ROS 2 (Humble+).
  • xacro, urdfdom (provides check_urdf), xmllint.
  • MuJoCo β‰₯ 2.3 (pip install mujoco).
  • Optional: Isaac Sim, for validating usd/ changes.
# clone
git clone https://github.com/limxdynamics/tron2-robot-description.git
cd tron2-robot-description

# ROS 1
catkin_make -DCATKIN_WHITELIST_PACKAGES=robot_description

# ROS 2
colcon build --packages-select robot_description

Directory conventions

tron2/<VARIANT>/
β”œβ”€β”€ urdf/    # generated URDF (do not hand-edit β€” regenerate from xacro)
β”œβ”€β”€ xacro/   # xacro sources of truth
β”œβ”€β”€ xml/     # MuJoCo model (robot.xml)
β”œβ”€β”€ meshes/  # STL, referenced by URDF and MuJoCo
└── usd/     # USD assets (optional per variant)
  • File names use PascalCase_Link.STL for links to match URDF <link name="…_Link">.
  • Do not commit CAD source files (.sldprt, .step, .iges, .blend).
  • Do not commit editor / OS junk β€” see .gitignore.

Coordinate & joint conventions

  • World frame: ROS-standard, x forward, y left, z up.
  • Root link: base_Link; IMU at base_imu.
  • Zero pose: URDF zero equals the factory-calibrated mechanical zero. Do not bake control offsets (e.g., the 180Β° hip yaw "knees-forward" offset) into the URDF β€” apply them in the controller.
  • Units: meters, kilograms, radians. Inertia is expressed in link-frame with the origin at the link's center of mass.

Regenerating URDF from xacro

The URDF files under tron2/*/urdf/ are the generated artifact; edits belong in xacro/. To regenerate:

# ROS 1
rosrun xacro xacro tron2/WF_TRON2A/xacro/robot.xacro -o tron2/WF_TRON2A/urdf/robot.urdf

# ROS 2
ros2 run xacro xacro tron2/WF_TRON2A/xacro/robot.xacro -o tron2/WF_TRON2A/urdf/robot.urdf

Repeat for each variant you touched. Commit both the xacro change and the regenerated URDF in the same commit.

Mesh & USD guidelines

  • STL must be binary format (ASCII STL is rejected by CI).

  • Collision meshes go in meshes/*_collision.STL and should be simplified (target < 5k triangles per link).

  • Visual meshes should not exceed 50k triangles per link.

  • STL headers must not contain internal paths or usernames. Before committing:

    find tron2 -iname "*.STL" -newer .git/HEAD | while read f; do
      head -c 80 "$f" | strings
    done
    

    Sanitize with any binary STL rewriter (e.g. admesh -b, or a small script that zeroes bytes 0–79 then rewrites the triangle count).

  • USD files are ASCII; run a grep for internal metadata before committing:

    grep -rE '(customLayerData|comment = "|"author"|"owner")' tron2/*/usd/*.usd
    

Verification before opening a PR

Run all of the following and paste the summary into the PR description:

# 1. URDF well-formed
for u in tron2/*/urdf/*.urdf; do check_urdf "$u"; done

# 2. MuJoCo can load the XML
for x in tron2/*/xml/*.xml; do
  python -c "import mujoco, sys; mujoco.MjModel.from_xml_path(sys.argv[1])" "$x"
done

# 3. xacro expands cleanly
for x in tron2/*/xacro/robot.xacro; do xacro "$x" > /dev/null; done

# 4. XML sanity
xmllint --noout tron2/*/urdf/*.urdf tron2/*/xml/*.xml

# 5. No unresolved TODO / proprietary / confidential markers
rg -n -i "unknown|todo|proprietary|confidential" \
   README.md THIRD_PARTY_NOTICES.md ASSETS.md

CI runs the same steps; local pre-checks save review round-trips.

Commit messages

Follow Conventional Commits:

type(scope): short imperative summary

Longer explanation if needed.

Signed-off-by: Your Name <you@example.com>

type ∈ feat | fix | docs | refactor | chore | ci | test | asset. scope is usually a variant folder (WF_TRON2A, SFYG_TRON2A, …) or meta for repo-wide changes.

Pull request checklist

  • xacro changes are accompanied by regenerated URDFs.
  • Meshes have been sanitized (STL header + USD metadata).
  • Verification commands run cleanly locally.
  • THIRD_PARTY_NOTICES.md updated if any external reference changed.
  • CHANGELOG.md has an entry under Unreleased.
  • No calibration values, firmware, weights, logs, bags, or media that discloses individuals or sites.
  • DCO sign-off on every commit.

Adding a new robot variant

  1. Create tron2/<VARIANT>/{urdf,xacro,xml,meshes,usd}/.
  2. Author the xacro; regenerate URDF; author the MuJoCo XML.
  3. Add a row to ASSETS.md and to the variant table in README.md.
  4. Add an entry to THIRD_PARTY_NOTICES.md for any new external hardware referenced (⚠ TO CONFIRM if not yet cleared).
  5. Add a smoke-test case to .github/workflows/ci.yml (add the new variant to the URDF / MuJoCo lists).

Sign-off (DCO)

We use the Developer Certificate of Origin. Every commit must be signed off:

git commit -s -m "your message"

Signing off certifies that you have the right to submit the change under the repository's license.

Code of conduct

Be respectful and constructive. Reports to contact@limxdynamics.com.