# Sensor Frame Mounting > --- name: sensor-frame-mounting description: 'Mount sensor frames in URDF. Use when adding camera, lidar, IMU, or GPS frame links and transforms to the robot description.' --- # Sensor Frame Mounting in URDF ## Principle Every sensor on the robot needs a frame in the TF tree. This frame is defined by a fixed joint in the URDF from the mounting link to the sensor link. The frame's name **must match** the `frame_id` parameter in the sensor's ROS driver. ```xml ``` The `origin` encodes the physical position and orientation of the sensor relative to the parent link. **Measure these offsets carefully**—errors here directly corrupt sensor data in the robot's coordinate frame. ## Camera Frames Cameras use an **optical frame** convention that differs from the ROS body convention: | Convention | X | Y | Z | |---|---|---|---| | ROS body (REP 103) | forward | left | up | | Optical frame | right | down | forward | Use an intermediate link to handle the rotation: ```xml ``` The rotation `rpy="${-pi/2} 0 ${-pi/2}"` converts from ROS body to optical frame: 1. Rotate -π/2 around x → z now points down, y points forward 2. Rotate -π/2 around z → x now points right, y points down, z points forward Set the camera driver's `frame_id` to `camera_optical_link`. ## OAK-D Camera (Stereo + IMU) The OAK-D has multiple sensors, each needing its own frame: ```xml ``` ## Lidar Frame Lidars typically follow ROS convention (x-forward, z-up). The critical parameter is the **height** (z offset): ```xml ``` If the lidar is mounted upside-down, add a π rotation around x: ```xml ``` **Wrong lidar height** is the most common cause of the costmap seeing the ground as an obstacle. If the scan hits the floor in simulation, the z-offset is too low. ## IMU Frame The IMU frame orientation determines how roll/pitch/yaw are interpreted by the EKF: ```xml ``` If the physical IMU is mounted rotated (e.g., 90° yaw), encode that in the origin: ```xml ``` Alternatively, handle the rotation in the EKF configuration or the IMU driver. Choose ONE place to apply the correction—never both. For `robot_localization` EKF, the IMU frame_id and the URDF link name must match, and the transform between `base_link` and `imu_link` must be correct. The EKF uses this transform to rotate IMU data into the robot's body frame. ## GPS Frame For outdoor robots, the GPS antenna position matters: ```xml ``` The GPS frame position affects the `navsat_transform_node` in `robot_localization`—it accounts for the lever arm between GPS antenna and the robot's base frame. ## Sensor Mounting Xacro Macro Reusable macro for simple sensor mounts: ```xml ``` ## Verification ```bash # Check that sensor frames exist in the TF tree ros2 run tf2_tools view_frames # Verify transform between base_link and sensor ros2 run tf2_ros tf2_echo base_link camera_optical_link ``` Common pitfalls: - Driver's `frame_id` doesn't match URDF link name → data appears at wrong location in RViz - Optical frame rotation wrong → image appears flipped or rotated - Sensor height off by a few cm → lidar sees ground, camera FOV is wrong