> 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/stretch4-body-repo/subsystems-and-hardware/primer_subsystems.md).

# Hardware Subsystems

This document provides an overview of the core hardware subsystems that make up the Stretch robot. It details how these subsystems are instantiated, managed, and configured, along with key parameters, status fields, and API calls for each.

## Subsystem Instantiation and Management

Subsystems are managed collectively by the `RobotCore` base class (and its descendants, like `Robot` or the `RobotServer`). During startup, `RobotCore` reads the `subsystems` list from the active parameter configuration (`robot_params`). It then instantiates the corresponding Python objects and stores them in its `self.subsystems` dictionary.

* `RobotCore` handles the base instantiation of `arm`, `lift`, `omnibase`, and `power_periph`.
* The `end_of_arm` and `line_sensor` subsystems are handled specifically by `Robot` or the server, as they rely on additional configuration (such as `robot.tool` to determine the active class) or separate multiprocess workers.

During the control loop, `RobotCore` aggregates data by calling `pull_status` and `push_command` on every active subsystem in the list.

### Disabling a Subsystem

If a hardware subsystem is physically removed or malfunctioning, you can prevent the software from attempting to instantiate and communicate with it by overriding the `subsystems` list in your `stretch_user_yaml`.

For example, to run the robot without the `end_of_arm` subsystem, you would add the following to your user YAML:

```yaml
robot:
  subsystems:
    - arm
    - lift
    - omnibase
    - power_periph
```

*(By omitting `end_of_arm`, the software will bypass its initialization entirely.)*

> **Note on Cameras:** The `cameras` directory is included within the `subsystems` folder structure, but cameras are not actively managed by the `RobotServer` or `RobotCore` control loop. The directory exists primarily to manage camera configuration parameters (like framerates, exposure limits, and intrinsic calibrations) within the unified parameter system.

***

## Subsystems Overview

### 1. Arm (`stretch4_body.subsystem.arm.Arm`)

Controls the horizontal prismatic joint (in/out extension) of the robot. It translates motor rotation into linear motion using a chain and sprocket mechanism.

### 2. Lift (`stretch4_body.subsystem.lift.Lift`)

Controls the vertical prismatic joint (up/down) of the robot, driven by a belt. It supports payload-based gravity feedforward compensation to safely lift and hold various end-of-arm tools.

### 3. OmniBase (`stretch4_body.subsystem.omnibase.OmniBase`)

Controls the differential/omnidirectional base using three stepper motor wheels. It provides real-time odometry and handles blended translational and rotational commands, as well as guarded collision detection.

### 4. PowerPeriph (`stretch4_body.subsystem.power_periph.PowerPeriphBase`)

Serves as the central hub for the robot's power state, IMU data, battery monitoring, and peripheral GPIO (LEDs, buzzers, fans, and runstop management).

### 5. EndOfArm (`stretch4_body.subsystem.end_of_arm.EndOfArm`)

A modular tool system dynamically instantiated based on the active `robot.tool` configuration (e.g., dexterous wrists, parallel grippers). It typically runs its hardware communication inside a separate high-frequency background worker process to decouple from the main server loop.

### 6. LineSensor (`stretch4_body.subsystem.line_sensor.LineSensorLoop`)

Interfaces with the downward-facing Pixart hardware sensors used for line following or drop-off detection. Similar to the EndOfArm, it runs in a dedicated background worker process for high-speed, non-blocking serial acquisition.

***

## Class Architecture

The following diagram illustrates how `RobotCore` manages the subsystems, and how specific hardware subsystems inherit from shared base classes (like `PrismaticJoint`).

```mermaid
classDiagram
    class RobotCore {
      +dict subsystems
    }
    class Robot
    
    class Arm
    class Lift
    class OmniBase
    class PowerPeriph
    class EndOfArm
    class LineSensor
    class PrismaticJoint

    RobotCore <|-- Robot
    RobotCore *-- Arm
    RobotCore *-- Lift
    RobotCore *-- OmniBase
    RobotCore *-- PowerPeriph
    RobotCore *-- EndOfArm
    RobotCore *-- LineSensor
    PrismaticJoint <|-- Arm
    PrismaticJoint <|-- Lift
```


---

# 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:

```
GET https://docs.hello-robot.com/stretch4-body-repo/subsystems-and-hardware/primer_subsystems.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.