> For the complete documentation index, see [llms.txt](https://docs.hello-robot.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hello-robot.com/stretch-4-quick-start-guide/robot-overview.md). # Robot Overview ## System Check Run a full hardware and software check to confirm the system is ready: ```bash stretch_system_check ``` If all checks pass, your robot is ready to go. Use `stretch_about` to print robot identity and configuration, and `stretch_params` to inspect all robot parameters. ## Homing If your robot needs to be homed, the system check will tell you. The homing procedure takes approximately 30 seconds and finds the zero position of all joints. It must be run once every time the robot is powered on: To home the robot: ```bash stretch_robot_home ``` \--# insert video of robot homing The robot will beep when finished. The motors will remember their homing state while the robot remains powered on — using the runstop, backdriving the robot, or restarting the NUC will not require rehoming. Powering the robot down completely will require homing again on the next boot. To stow the robot to its compact travel pose: ```bash stretch_robot_stow ``` \--# insert video of robot stowing ## Runstop The physical runstop button on the side of the robot's head immediately cuts power to all motors. The `stretch_runstop` tool lets you toggle the runstop programmatically from the terminal. \--# we already mentioned this in quick start should we point to it? ## Monitoring To monitor all robot devices, sensors, and activity in real time, including joint states, battery, and subsystem status: ```bash stretch_monitor_devices ``` This tool provides a unified live dashboard of the robot's state. \--# this tool exists in stretch\_production\_tools\_ii, worth it to port to stretch4\_body ## Motors and Joints \--# add videos for each ### Omnibase Stretch 4 has a triangular omnibase, consisting of three holonomic closed-loop stepper motors each driving one wheel. Wheel numbering increases counter-clockwise, with wheel 0 to the left of the forward direction. This is consistent with the ROS frame convention where X+ is forward and Y+ is to the left, forming a right-handed coordinate frame. The omnibase supports full planar motion — forward, sideways, diagonal, and rotation in place, all simultaneously. It also supports guarded contact sensitivity, which can be calibrated and tuned per use case. To jog the base: ```bash stretch_omni_base_jog ``` ### Lift The lift provides vertical translation of the arm, reaching up to 47 inches high and all the way down to the ground. It is driven by a closed-loop stepper motor through a low gear-ratio belt drive, providing smooth and precise motion. ```bash stretch_lift_jog ``` ### Arm The arm comprises 4 telescoping links set on rollers, extending 21.6 inches beyond the base footprint and retracting to stow within it. Its proprietary drivetrain is driven by a stepper motor with closed-loop control and current sensing, enabling contact detection during motion. In combination, the lift, arm, and mobile base provide three orthogonal axes of motion — a Cartesian system for end-effector placement. ```bash stretch_arm_jog ``` ### Contact Sensitivity (Guarded Contact) Stretch's lift, arm, and omnibase joints have a contact detection system called Guarded Contact. This safety feature limits the forces Stretch can apply to a person or its environment, and can be tuned for your application. Guarded Contact uses current sensing to detect when actuator effort exceeds a user-specified threshold during motion. When triggered, the safety controller halts the joint until a new movement command is received. ### Feetech Motors The wrist and gripper joints use Feetech servo motors, controlled over a TTL serial bus. To monitor Feetech motor status: ```bash stretch_feetech_monitor ``` #### Feetech Errors and Reset Feetech motors can enter an error state from over-force or over-temperature events. When in this state, the motor becomes backdrivable, stops responding to commands, and the LED on the motor body blinks red. Powering the robot down completely will clear this error. Note: rebooting only the NUC will NOT clear it, as the Feetech motors remain powered. A faster way to clear the error: ```bash stretch_feetech_reboot ``` This reboots all Feetech motors and resets their error status. You will need to re-run homing after doing this since the wrist\_yaw and gripper joints lose their homed positions. ## Head Cameras Stretch 4 has a Luxonis OAK-FFC-3P camera module mounted in the head with three cameras: | Camera | Type | Resolution | Target FPS | | ------ | --------------------- | ---------- | ---------- | | Left | Fish-eye wide angle | 1920×1200 | 30 | | Right | Fish-eye wide angle | 1920×1200 | 30 | | Center | High-resolution color | 4032×3040 | 10 | The left and right cameras are fish-eye wide-angle cameras providing a broad environmental field of view. The center camera is a high-resolution color camera. All three are angled to maximize combined visual coverage in every frame. To display any combination of camera feeds and open them in `rerun` or `opencv` : ```bash stretch_camera_show --left --rerun stretch_camera_show --center --opencv stretch_camera_show --right --rerun stretch_camera_show --left_right_center --opencv ``` {% hint style="info" %} 1. use either --rerun or --opencv (not both) in conjunction with the choice of camera combination. 2. use the flag -h to see all options {% endhint %} ### Emulated RGBD from Head Cameras The head cameras can be fused with the head Hesai lidars to produce RGBD (color + depth) point clouds. To visualize this: ```bash stretch_rgbd_show ``` ### Camera Focus and Calibration Camera focus is adjusted and intrinsics are calibrated using the factory calibration pipeline. After calibration, cross-calibration between cameras and lidars is also performed during the bringup process to align all sensor modalities spatially. ## Dexterous Wrist Stretch 4 has a three degree-of-freedom wrist with yaw, pitch, and roll actuation — all driven by Feetech actuators. | Axis | Raw Servo Range | Notes | | ----------- | --------------- | -------------------------------------------------------------------------- | | Wrist Yaw | 310° | `range_deg: [-65, 245]` | | Wrist Pitch | 310° | `range_deg: [-65, 245]` — effective range reduced by self-collision limits | | Wrist Roll | 310° | `range_deg: [-65, 245]` | To jog individual wrist joints: ```bash stretch_dex_wrist_jog ``` To home all wrist joints: ```bash stretch_dex_wrist_home ``` Individual axis homing is also available with `stretch_wrist_yaw_home`, `stretch_wrist_pitch_home`, and `stretch_wrist_roll_home`. ## Gripper The compliant gripper is a robust single-degree-of-freedom end-effector. A Feetech actuator drives the center of the spring mechanism, which causes the outer fingers to flex and provide a grasping force. ```bash stretch_gripper_jog stretch_gripper_home ``` ### Gripper Cameras Stretch 4 has two OAK-D-SR (Short Range) cameras mounted at the gripper, providing stereo depth for in-hand manipulation tasks. These are detected as a separate Luxonis device from the head cameras (2-sensor device vs. the 3-sensor head device). ```bash stretch_camera_show --gripper ``` ## Sensors Stretch 4 includes the following sensors: * Hesai JT128 3D LiDAR × 2 (Left and Right, mounted on the head) * Luxonis OAK-FFC-3P Camera Module (Head: 3-camera array) + OAK-D-SR (Gripper: stereo pair) * Speaker (mounted at the bottom of the head) * Pixart J3 Line Sensor Array (base, floor-facing) ### Hesai JT128 3D LiDAR (Head) Stretch 4 has two Hesai JT128 3D LiDAR units mounted on the head — a left lidar and a right lidar — providing full 3D point cloud coverage of the environment. These are used for mapping, navigation, and RGBD fusion with the head cameras. Each lidar communicates over Ethernet. The NUC holds a single network profile with two IP addresses to communicate with both lidars and the Jetson simultaneously:
DeviceIP AddressDescription
Left lidar192.168.1.202Hesai JT128 left
Right lidar192.168.1.201Hesai JT128 right
NUC (Lidar subnet)192.168.1.2Onboard computer — lidar communications
NUC (Jetson subnet)192.168.1.100Onboard computer — Jetson communications
Jetson192.168.1.101AI co-processor
### Speaker and Microphone The robot has a speaker and noise-cancelling microphone mounted at the bottom of the head, allowing Stretch to communicate from across a room. To test audio output: ```bash stretch_audio_test ``` ### Line Sensor Array Stretch 4 includes a floor-facing GreatScott GS2 line sensor array on the base. This array continuously scans the floor in front of the robot and uses an on-robot model to classify the surface as floor or obstacle, enabling low-latency hazard detection independent of the lidar. The line sensor runs in a dedicated background worker process at approximately 30 Hz, and its output is used by the omnibase to automatically limit velocity when an obstacle is detected in the direction of travel. To visualize the line sensor: ```bash stretch_line_sensor_viz_3d ``` ## LED Eyes and Lightbar The robot head has two LED eye displays. These support a set of built-in animations including idle glow, blinking, directional gaze, rainbow spin, alert, and happy states: ```bash stretch_eye_animations ``` The head also has a programmable RGB LED lightbar. The lightbar can be triggered and tested via `stretch_power_periph_jog`. ## NVIDIA Jetson (AI Co-processor) Stretch 4 includes an NVIDIA Jetson Orin module as a dedicated AI co-processor, directly connected to the NUC via Ethernet. ### Software Environment The Jetson runs with: * **OS:** Ubuntu 22.04 + JetPack 6.1 * **Custom Docker container** with: ROS 2 Jazzy, PyTorch, CUDA (cu129), Zenoh, Ultralytics, and OpenCV Bridge for NVIDIA Jetson ### Accessibility The NVIDIA Jetson boots up automatically whenever the robot is powered on. Passwordless SSH is pre-configured, so you can seamlessly access the Jetson from the NUC using the following command: ```bash ssh jetson1@192.168.1.101 ``` {% hint style="warning" %} **Note:** *If the Jetson fails to boot, you can manually power it on from the NUC using `stretch_power_periph_jog -d`. To forcefully power it off from the NUC, use `stretch_power_periph_jog -c`)* {% endhint %} ### Internet Connectivity To enable system updates and software package installations, there is a Wi-Fi dongle attached directly to the Jetson processor. You can connect the Jetson's Wi-Fi dongle to your local internet using the command line interface (CLI). Once logged into the Jetson via SSH, use the `nmcli` network manager to connect to your Wi-Fi network: ```bash sudo nmcli device wifi connect "" password "" ``` Once connected, you can verify internet access by pinging an external server: ```bash ping 8.8.8.8 ``` ### GPU Offloading The Jetson communicates with the NUC via Zenoh for ROS 2 topic bridging. This enables offloading compute-heavy tasks such as YOLO object detection or pose estimation to the Jetson's GPU, while the NUC handles robot control. The Jetson subscribes to image topics published by the NUC and returns inference results. ## Software Architecture Stretch 4 uses a client/server architecture in `stretch4_body`: * **`stretch_body_server`** runs a 100 Hz control loop on the NUC, managing all hardware state * Application code connects via `RobotClient` to issue commands * A C++ transport backend handles non-blocking USB communication to all motor controllers in parallel The 100 Hz control loop follows this sequence every tick: 1. Pull status from all devices 2. Update sentries (safety watchdogs) 3. Ingest commands from the Robot Client 4. Run active controllers and behaviors 5. Compute safe motion limits 6. Push safe commands to motor controllers To launch the body server: ```bash stretch_body_server --launch ``` ## Gamepad Teleoperation Stretch 4 ships with an Xbox controller and supports two control mappings: ### 1. Joint Space (default) Direct joint-level control of the robot. All controls are summarized below:
ControlAction
Base Controls
Left StickTranslate base (XY)
LB / RBRotate base
Hold LB + RB, Right StickAnalog base rotation
RT + Left StickStraight-line base movement
Arm Controls
Right StickWrist Pitch (Y) and Yaw (X)
D-Pad Up / DownLift up / down
D-Pad Left / RightArm retract / extend
A / B ButtonsClose / Open gripper
RT + LB / RBWrist Roll
Modifiers
LTPrecision mode (reduce speed)
### 2. Flying Gripper IK IK-based Cartesian control of the gripper. Point the gripper toward your target with the Right Stick, then move toward it with the Left Stick: | Control | Action | | ------------------ | ------------------------------------- | | Left Stick | Move toward target (translation) | | Right Stick | Point gripper at target (orientation) | | D-Pad Up / Down | Lift up / down | | D-Pad Left / Right | Wrist Roll | | A / B Buttons | Close / Open gripper | | LT | Precision mode (reduce speed) | ### Special Functions
InputAction
Y Button (tap)Cycle control mapping (Joint Space ↔ Flying Gripper IK)
RT + A (tap)Cycle motion speed profile (Slow / Medium / Fast)
RT + B (tap)Cycle contact sensitivity profile
Start Button (tap, unhomed)Home the robot
Start Button (tap, homed)Switch gripper handedness (without motion)
Start Button (hold 3s, homed)Switch gripper handedness (with motion)
RT + Select (tap)Announce current settings (handedness, speed, sensitivity, mapping)
RT + Select (hold 2s)Stow the robot
X Button (hold 0.5s)Execute custom function command
To launch gamepad teleoperation: ```bash stretch_gamepad_teleop ``` ## Developer I/O Stretch 4 contains additional ports connected to the onboard NUC that can be used for accessories: * **Trunk:** 1× USB-A 3.0 ports, 2x USB-A 2.0 ports, 1× Ethernet port, 1× HDMI port. * **Head (top):** 1× USB-A 2.0 port, 1x USC-C Port * **End-of-arm:** 1× USB-A 2.0 port * **Wrist:** Quick-connect mechanism for tool attachment. There are also threaded mounting points on the head to add additional sensors. ## Key Tools Reference
ToolDescription
stretch_body_serverStart / stop / release the 100 Hz robot control server
stretch_robot_homeHome all robot joints
stretch_robot_stowStow the robot to its compact travel pose
stretch_runstopToggle the runstop programmatically
stretch_system_checkFull hardware and software system check
stretch_aboutPrint robot identity and configuration
stretch_paramsPrint all robot parameters
stretch_battery_checkCheck battery state of charge
stretch_statusLive robot status display
stretch_joint_vizJoint state visualization
stretch_collision_vizVisualize self-collision safety margins
stretch_gamepad_teleopLaunch Xbox gamepad teleoperation
stretch_puppet_teleopLaunch puppet (backdriving) teleoperation
stretch_omni_base_jogJog the omnibase
stretch_lift_jogJog the lift
stretch_arm_jogJog the arm
stretch_arm_homeHome the arm
stretch_lift_homeHome the lift
stretch_gripper_jogJog the gripper
stretch_gripper_homeHome the gripper
stretch_dex_wrist_jogJog dex wrist joints
stretch_dex_wrist_homeHome all dex wrist joints
stretch_feetech_rebootReboot Feetech motors and clear errors
stretch_feetech_monitorMonitor Feetech motor status
stretch_camera_showLive camera feed viewer (configurable)
stretch_rgbd_showEmulated RGBD from head cameras + lidar
stretch_line_sensor_viz_3d3D visualization of line sensor data
stretch_power_periph_jogManually control power periph (Jetson, fans, lidar, etc.)
stretch_eoa_powerToggle end-of-arm power
stretch_eye_animationsRun LED eye animations
stretch_audio_testTest speaker output
stretch_pose_playPlay back recorded robot poses
stretch_pose_recordRecord robot poses
stretch_pose_editEdit recorded pose files
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.hello-robot.com/stretch-4-quick-start-guide/robot-overview.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.