Fejemis Description ROS2

Back to Fejemis ROS2 Software

Purpose

fejemis_description is the robot description package for Fejemis. It defines the robot model using URDF/Xacro and publishes the TF model state so the rest of the ROS 2 stack can use a consistent robot geometry.

The package is responsible for:

• Building the Fejemis robot model from modular xacro files.
• Publishing robot_description and TF through robot_state_publisher.
• Providing a simulation-friendly wheel configuration through launch arguments.
• Keeping a shared frame and link structure used by simulation, mapping, and navigation.

Package Layout

Important folders:

• launch - launch files for model generation and state publishing.
• xacro - modular robot model definition files.
• config - controller/simulation-related configuration.

Main xacro files:

• xacro/robot.urdf.xacro - top-level robot assembly file.
• xacro/robot_core.xacro - chassis and base links.
• xacro/robot_wheels.xacro - drive wheels and Gazebo diff-drive plugin.
• xacro/robot_castor.xacro - castor wheel definition.
• xacro/sensor_imu.xacro - IMU and magnetometer links/sensors.
• xacro/sensor_lidar.xacro - LiDAR link and simulated scan sensor.
• xacro/sensor_depth_camera.xacro - depth camera and optical frame.
• xacro/utils_inertial.xacro and xacro/utils_colors.xacro - reusable inertial and visual macros.

Launch File

launch/model.launch.py

This launch file generates the URDF from xacro and starts robot_state_publisher.

Launch arguments:

• use_sim_time - enables simulation clock when true. Default: false.

Behavior:

• Processes fejemis_description::xacro/robot.urdf.xacro with xacro.
• Passes fixed_wheels:=<use_sim_time> into xacro.
• Publishes robot_description parameter to robot_state_publisher.
• Publishes the model TF tree for downstream packages.

Model Composition

The top-level model in robot.urdf.xacro assembles the robot in this order:

• Core chassis: xacro:core
• Drive wheels: xacro:wheels
• Castor wheel: xacro:castor
• IMU and magnetometer: xacro:imu_sensor
• LiDAR: xacro:lidar
• Depth camera: xacro:depth

There is also an optional camera macro (currently commented in the top-level xacro).

Main Links and Frames

Common links/frames provided by the description:

• base_link - primary base frame for navigation and odometry integration.
• chassis - main physical body link.
• left_wheel and right_wheel - drive wheel links.
• laser_frame - LiDAR mounting and scan frame in simulation.
• imu_link - IMU and magnetometer frame.
• depth_link and depth_link_optical - depth camera body and optical frame.

These frames are consumed by mapping/localisation and simulation bridge layers.

Simulation-Specific Behavior

The wheel macro supports both fixed and rotating wheel joints:

• Real robot path: wheel joints are fixed in the model launch context.
• Simulation path: wheels are set to continuous joints when simulation mode is enabled.

Gazebo systems configured in robot_wheels.xacro:

• gz::sim::systems::DiffDrive
• gz::sim::systems::JointStatePublisher

Diff-drive plugin settings include:

• Wheel separation: 0.3847
• Wheel diameter: 0.2
• Command topic: /model/fejemis/cmd_vel
• Odometry topic: /model/fejemis/odom
• Frame IDs: odom and base_link

Drive wheel friction is increased in simulation to reduce slip, while castor behavior is defined separately in the castor xacro.

Sensor Simulation Topics

The description also defines simulated sensor outputs used by the bridge layer:

• LiDAR: /model/fejemis/scan
• IMU: /model/fejemis/imu
• Magnetometer: /model/fejemis/mag
• Depth camera: /model/fejemis/depth_camera

These topics are later bridged into ROS topics by fejemis_sim.

Typical Usage

Start robot description publisher:

```bash ros2 launch fejemis_description model.launch.py ```

Start with simulation time:

```bash ros2 launch fejemis_description model.launch.py use_sim_time:=true ```

In most full-system runs, this launch file is included by top-level bringup (for example in simulation launch stacks).

Relationship To Other Packages

• fejemis_sim uses this package to spawn the robot from /robot_description.
• fejemis_maploc and Nav2 depend on the frame structure defined here.
• Sensor and odometry pipelines assume the link names and frame conventions from this model.