# anandchauhan21/esp_101 architecture

> Architecture diagram of the GitHub repository anandchauhan21/esp_101, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anandchauhan21/esp_101
- Repository: https://github.com/anandchauhan21/esp_101

## Overview

##### Project type & purpose (from file tree + README)
This repo is an **embedded/robotics starter kit** centered on **ESP32/ESP8266** development, demonstrating:
- **Sensor integration** (notably ultrasonic distance sensing: `ultrasonicTest.py`, obstacle avoidance: `Obstacle_Avoidance.py`)
- **Actuator control** (motors, servos, buzzer, LEDs: `motortest.py`, `two_motor.py`, `servoTest.py`, `buzzerTest.py`, `ledTest.py`)
- **Robot behaviors** (square path, obstacle avoidance: `square_path.py`, `Obstacle_Avoidance.py`, `sugarTank1_1.py`)
- **Concurrency** (threading: `multithread.py`)
- **Wi‑Fi control / connectivity** (hinted by root `esp32_wificar.py`)

So your “system” is not just software modules: it is **physical hardware + firmware/app logic + optional networked controller/client**.

##### What the file structure implies architecturally
Top-level:
- `sugarTank/`: a **robot/tank platform** with many focused scripts:
- *Hardware test utilities*: `*_Test.py` (LED, buzzer, servo, ultrasonic, motor)
- *Motion primitives*: `two_motor.py`, `square_path.py`
- *Behavioral logic*: `Obstacle_Avoidance.py`, `sugarTank1_1.py`
- *Concurrency*: `multithread.py`
- `media/`, `sugarTank/README.md`: project docs/assets

This suggests a **module-per-feature** style typical of embedded learning repos:
- Low-level GPIO/PWM driving modules
- Sensor read modules
- Higher-level behavior scripts composing those primitives
- Optional communication layer (Wi‑Fi)

##### Microcontroller Firmware (Python/MicroPython script)
- Entry scripts: `sugarTank1_1.py`, `Obstacle_Avoidance.py`, `square_path.py`, `esp32_wificar.py` (depending where it runs)
##### Hardware Abstraction / Drivers
- GPIO/PWM control for motors/servo/LED/buzzer
- Ultrasonic timing/echo measurement
##### Control / Behavior Layer
- Obstacle avoidance logic, path-following, motion primitives
##### Networking Layer (Wi‑Fi)
- Command receiver / telemetry sender (if used)
##### Physical Components
- Motor driver (H-bridge), motors, servo
- Ultrasonic sensor (HC-SR04 style)
- LED, buzzer

**Key point:** for embedded projects, showing **signals** matters:
- PWM lines to motors/servo
- Digital IO to LED/buzzer
- Trigger/Echo lines for ultrasonic
- Wi‑Fi as a separate communication channel

Suggested components (labeled with file names):
- `Obstacle_Avoidance.py` → **ObstacleAvoidanceController**
- depends on **UltrasonicSensor**
- commands **MotorController**
- `square_path.py` → **PathPlanner (SquarePath)**
- commands **MotorController**
- `two_motor.py` / `motortest.py` → **MotorController / MotorTestHarness**
- `servoTest.py` → **ServoController / ServoTestHarness**
- `ultrasonicTest.py` → **UltrasonicSensor / SensorTestHarness**
- `buzzerTest.py` → **BuzzerController**
- `ledTest.py` → **LEDController**
- `multithread.py` → **Scheduler/Concurrency Wrapper**
- Separate loops/tasks: sensor polling, motor control, networking

Test scripts explicitly as “diagnostic mode” components; they are part of how the system is operated and validated.

- **ObstacleAvoidanceController → MotorController**: “set speed(left,right)”, “stop()”, “turn()”
- **UltrasonicSensor → ObstacleAvoidanceController**: “distance_cm”
- **Wi‑Fi Command Handler → Behavior Layer**: “manual drive command”, “mode switch (auto/manual)”
- **Behavior Layer → Actuators**: PWM duty cycle, direction pins, servo angle
- **Sensor polling task → shared state** (if multithreaded): show concurrency boundary and synchronization assumptions (even if simplistic)

- **ESP32 → Cloud endpoint**: HTTP/MQTT telemetry (mark as optional / future)

##### Architectural patterns/design principles present (or implied)
- **Layering**: Behavior → Drivers → Hardware
- **Composition over inheritance** (typical scripting style): behavior scripts compose sensor + motor primitives
- **Mode-based operation**: “test mode” vs “autonomous mode” vs “manual/Wi‑Fi mode”
- **Concurrency** (explicit via `multithread.py`): separate loops for responsiveness

##### Labels

- **Signal/protocol**: PWM, GPIO, Wi‑Fi (HTTP/MQTT/TCP/UDP), thread queue/shared state
- **Payload**: distance_cm, motor_speed, steering_angle, command JSON, etc.

##### “Don’t overthink it” detail strategy (as requested)
Break into as many components as possible by following this rule:

**Panel A — System Context**
- User ↔ Phone/Laptop Controller ↔ Wi‑Fi AP ↔ ESP32 Robot
- Optional: ESP32 ↔ Cloud Endpoint

**Panel B — Hardware + Firmware**
- ESP32
- GPIO/PWM → Motor Driver → Left/Right Motors
- PWM → Servo
- GPIO → LED
- GPIO → Buzzer
- GPIO (Trig/Echo) ↔ Ultrasonic Sensor
- Power → ESP32 + Motor Driver (noting shared ground)

**Panel C — Software Components (file-mapped)**
- Main behavior: `sugarTank1_1.py` (if it is the main integrator)
- Controllers: `Obstacle_Avoidance.py`, `square_path.py`
- Drivers/tests: `two_motor.py`, `motortest.py`, `servoTest.py`, `ultrasonicTest.py`, `ledTest.py`, `buzzerTest.py`
- Concurrency: `multithread.py`
- Wi‑Fi control: `esp32_wificar.py` (with a note “runs on ESP32” or “runs on host” depending on confirmation)

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Panel A — System Context
  %% =========================
  subgraph "Panel A — System Context (Level 0)"
    direction TB

    User["User / Operator"]:::external
    Client["Client Device\n(Phone/Laptop Controller)"]:::external
    AP["Wi‑Fi AP / Router"]:::network
    Cloud["Optional Cloud/Web Endpoint\n(Telemetry/Control)"]:::optional

    subgraph "ESP32 Robot System Boundary"
      direction TB
      Robot["ESP32 Robot (Firmware + Hardware)"]:::system
    end

    User -->|"issuesCommands"| Client
    Client -->|"WiFiControl+Telemetry"| AP
    AP -->|"WiFiCommands+Telemetry"| Robot
    Robot -.->|"optionalTelemetry(HTTP/MQTT)"| Cloud
  end

  %% ==================================
  %% Panel B — Hardware + Firmware Blocks
  %% ==================================
  subgraph "Panel B — Hardware + Firmware (Level 1)"
    direction TB

    subgraph "Firmware Runtime (MicroPython/Python Scripts)"
      direction TB
      FWEntry["Firmware Entry / Mode Selector\n(auto/manual/test)"]:::software
      WiFiAmbig["Wi‑Fi Control Script\n(ambiguous runtime: ESP32 or host)\n\"esp32_wificar.py\""]:::software
      Concurrency["Concurrency / Scheduler\n\"multithread.py\""]:::software
      Behavior["Behavior Layer\n(Obstacle avoidance / path)"]:::software
      Drivers["Hardware Abstraction / Drivers\n(GPIO/PWM timing)"]:::software
    end

    subgraph "ESP32 MCU"
      direction TB
      ESP32["ESP32/ESP8266 MCU\nGPIO + PWM + Wi‑Fi Radio"]:::hardware
    end

    subgraph "Actuators"
      direction TB
      HBridge["Motor Driver (H-bridge)"]:::hardware
      Motors["Left/Right DC Motors"]:::hardware
      Servo["Servo (Steering/Pan)"]:::hardware
      LED["LED"]:::hardware
      Buzzer["Buzzer"]:::hardware
    end

    subgraph "Sensors"
      direction TB
      Ultrasonic["Ultrasonic Distance Sensor\n(Trig/Echo timing)"]:::hardware
    end

    subgraph "Power"
      direction TB
      Battery["Battery / Regulator\n(sharedGND)"]:::hardware
    end

    %% Firmware internal flow
    FWEntry -->|"selectsMode"| Behavior
    FWEntry -->|"optionalWiFiMode"| WiFiAmbig
    Concurrency -->|"runsTasks(sensorLoop/motorLoop/netLoop)"| Behavior
    Behavior -->|"callsGPIO/PWM"| Drivers
    Drivers -->|"pinWrites/PWM"| ESP32

    %% ESP32 to hardware signals
    ESP32 -->|"PWM+DIR"| HBridge
    HBridge -->|"motorPower"| Motors

    ESP32 -->|"PWM(servoAngle)"| Servo
    ESP32 -->|"GPIO(digitalOut)"| LED
    ESP32 -->|"GPIO(digitalOut/tonePWM)"| Buzzer
    ESP32 -->|"GPIO(Trig)"| Ultrasonic
    Ultrasonic -->|"GPIO(Echo pulse)"| ESP32

    %% Power distribution
    Battery -->|"regulatedPower"| ESP32
    Battery -->|"motorPower"| HBridge
  end

  %% ==========================================
  %% Panel C — Software Components (Level 2, file-mapped)
  %% ==========================================
  subgraph "Panel C — Software Components (mapped to files)"
    direction TB

    DocsTop["Project README\n\"README.md\""]:::docs
    DocsSugar["SugarTank README\n\"sugarTank/README.md\""]:::docs
    Media["Docs Media/Assets\n\"sugarTank/media/\""]:::docs

    subgraph "SugarTank Robot Platform (sugarTank/)"
      direction TB

      MainIntegrator["Main Integrator / Autonomous Robot\n\"sugarTank1_1.py\""]:::software

      subgraph "Behaviors"
        direction TB
        ObstacleAvoid["ObstacleAvoidanceController\n\"Obstacle_Avoidance.py\""]:::software
        SquarePath["PathPlanner (Square Path)\n\"square_path.py\""]:::software
      end

      subgraph "Motion / Actuation Primitives"
        direction TB
        TwoMotor["MotorController (Two Motor)\n\"two_motor.py\""]:::software
        ServoTest["Servo Test Harness\n\"servoTest.py\""]:::test
      end

      subgraph "Sensors / Diagnostics"
        direction TB
        UltrasonicTest["Ultrasonic Sensor Test\n\"ultrasonicTest.py\""]:::test
      end

      subgraph "Device Diagnostics (Test Mode)"
        direction TB
        MotorTest["Motor Test Harness\n\"motortest.py\""]:::test
        LedTest["LED Test Harness\n\"ledTest.py\""]:::test
        BuzzerTest["Buzzer Test Harness\n\"buzzerTest.py\""]:::test
      end

      ThreadDemo["Threading Demo / Wrapper\n\"multithread.py\""]:::software
    end

    WiFiTop["Wi‑Fi Control / Connectivity Entry\n\"esp32_wificar.py\""]:::software

    %% Composition / dependencies
    MainIntegrator -->|"composes"| ObstacleAvoid
    MainIntegrator -->|"composes"| SquarePath
    MainIntegrator -->|"uses"| TwoMotor
    MainIntegrator -->|"optionalUses"| WiFiTop
    MainIntegrator -->|"optionalUses"| ThreadDemo

    ObstacleAvoid -->|"reads distance_cm"| UltrasonicTest
    ObstacleAvoid -->|"setSpeed/turn/stop"| TwoMotor

    SquarePath -->|"setSpeed/turn/stop"| TwoMotor

    ThreadDemo -->|"separatesLoops(sharedState)"| ObstacleAvoid
    ThreadDemo -->|"separatesLoops(sharedState)"| TwoMotor
    ThreadDemo -->|"optionalNetLoop"| WiFiTop

    %% Test scripts drive same primitives/hardware
    MotorTest -->|"directMotorControl"| TwoMotor
    ServoTest -->|"drivesServoPWM"| Drivers
    UltrasonicTest -->|"measuresEchoTiming"| Drivers
    LedTest -->|"gpioToggle"| Drivers
    BuzzerTest -->|"tonePWM/gpio"| Drivers

    %% Docs relationships
    DocsTop -->|"documents"| WiFiTop
    DocsTop -->|"documents"| MainIntegrator
    DocsSugar -->|"documents"| MainIntegrator
    Media -->|"usedBy"| DocsSugar
  end

  %% Cross-panel bindings (conceptual)
  WiFiAmbig -->|"implementationOf"| WiFiTop
  Concurrency -->|"implementationOf"| ThreadDemo
  Behavior -->|"implementedBy"| ObstacleAvoid
  Behavior -->|"implementedBy"| SquarePath
  Drivers -->|"controls"| ESP32

  %% =========================
  %% Click Events (from mapping)
  %% =========================
  click WiFiTop "https://github.com/anandchauhan21/esp_101/blob/main/esp32_wificar.py"
  click WiFiAmbig "https://github.com/anandchauhan21/esp_101/blob/main/esp32_wificar.py"
  click MainIntegrator "https://github.com/anandchauhan21/esp_101/blob/main/sugarTank/sugarTank1_1.py"
  click ObstacleAvoid "https://github.com/anandchauhan21/esp_101/blob/main/sugarTank/Obstacle_Avoidance.py"
  click SquarePath "https://github.com/anandchauhan21/esp_101/blob/main/sugarTank/square_path.py"
  click TwoMotor "https://github.com/anandchauhan21/esp_101/blob/main/sugarTank/two_motor.py"
  click MotorTest "https://github.com/anandchauhan21/esp_101/blob/main/sugarTank/motortest.py"
  click UltrasonicTest "https://github.com/anandchauhan21/esp_101/blob/main/sugarTank/ultrasonicTest.py"
  click ServoTest "https://github.com/anandchauhan21/esp_101/blob/main/sugarTank/servoTest.py"
  click BuzzerTest "https://github.com/anandchauhan21/esp_101/blob/main/sugarTank/buzzerTest.py"
  click LedTest "https://github.com/anandchauhan21/esp_101/blob/main/sugarTank/ledTest.py"
  click ThreadDemo "https://github.com/anandchauhan21/esp_101/blob/main/sugarTank/multithread.py"
  click Concurrency "https://github.com/anandchauhan21/esp_101/blob/main/sugarTank/multithread.py"
  click DocsTop "https://github.com/anandchauhan21/esp_101/blob/main/README.md"
  click DocsSugar "https://github.com/anandchauhan21/esp_101/blob/main/sugarTank/README.md"
  click Media "https://github.com/anandchauhan21/esp_101/tree/main/sugarTank/media/"
  click Robot "https://github.com/anandchauhan21/esp_101/tree/main/sugarTank/"
  click MainIntegrator "https://github.com/anandchauhan21/esp_101/tree/main/sugarTank/"
  click DocsSugar "https://github.com/anandchauhan21/esp_101/tree/main/sugarTank/"

  %% =========================
  %% Styles
  %% =========================
  classDef system fill:#1f2937,stroke:#111827,color:#ffffff,stroke-width:2px;
  classDef software fill:#2563eb,stroke:#1e40af,color:#ffffff,stroke-width:1.5px;
  classDef test fill:#1d4ed8,stroke:#1e3a8a,color:#ffffff,stroke-dasharray:4 3,stroke-width:1.5px;
  classDef hardware fill:#16a34a,stroke:#065f46,color:#ffffff,stroke-width:1.5px;
  classDef external fill:#0ea5e9,stroke:#075985,color:#ffffff,stroke-width:1.5px;
  classDef network fill:#f59e0b,stroke:#92400e,color:#111827,stroke-width:1.5px;
  classDef optional fill:#fb7185,stroke:#9f1239,color:#111827,stroke-dasharray:6 4,stroke-width:1.5px;
  classDef docs fill:#a78bfa,stroke:#5b21b6,color:#111827,stroke-width:1.5px;
```
