# alenshaju12/toby architecture

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

- Interactive diagram: https://gitdiagram.com/alenshaju12/toby
- Repository: https://github.com/alenshaju12/toby

## Overview

##### What this project is (type + purpose)
**Toby** is a small robotics system (hardware + software) for a **Raspberry Pi Zero W–controlled quadruped** driven by **8 hobby servos** through a **PCA9685 PWM servo controller**, with a **local “remote control” script** that sends commands to the Pi.

From the repo:
- **Mechanical CAD/print artifacts:** `3D Models/*.STL`, `Assembled Model.STL`
- **Robot-side runtime scripts (on the Pi):** `Code on Raspberry pi/*.py` (forward/sit/standup/stop/wave…)
- **Local controller:** `mainl.py` (run on your laptop/desktop; uses **paramiko** per README → SSH remote execution)
- **Servo calibration / low-level control:** `servo.py` (calibrate servos to 90°)

##### Local Control Plane (Operator side)
- `mainl.py`
- Dependency: `paramiko` (SSH client)
- Responsibility: prompts user, maps commands (“walk/sit/standup/wave/stop”) to remote actions on the Pi

##### Robot Compute Plane (Raspberry Pi Zero W)
- Folder: `Code on Raspberry pi/`
- `forward.py`, `sit.py`, `sitdown.py`, `standup.py`, `stop.py`, `wave1.py`
- Likely responsibility: motion routines (sets multiple servo angles over time)

##### Actuation Plane (Servo control + motors)
- `servo.py` (calibration / servo positioning helper)
- Hardware: **PCA9685** servo controller (I2C in, PWM out)
- Hardware: **8x MG90** servos
- Mechanical: printed legs/body (`*.STL`)

- Power source (battery / 5V supply)
- Separate power domains (common in servo robots): servo power vs Pi power, shared ground

The minimum accurate runtime flow is:

##### Pi runs one of the motion scripts (e.g., `forward.py`)
4. Motion script uses an I2C library (commonly Adafruit PCA9685 driver) to send **I2C commands** to PCA9685
##### Servos move legs → robot changes pose/gait

- Local PC →(Wi‑Fi/SSH)→ Raspberry Pi
- Raspberry Pi →(I2C)→ PCA9685
- PCA9685 →(PWM x8 channels)→ Servos
- Servos →(mechanical linkage)→ Legs/Body (3D printed)

“setup/calibration” flow:
- `servo.py` is executed on the Pi to set all servos to **90°** before assembly/calibration.

- **`mainl.py` (Command Console / Remote Controller)**
- uses **Paramiko (SSH)**
- sends “walk/sit/standup/wave/stop”

- **Motion scripts (run on Pi):**
- `Code on Raspberry pi/forward.py`
- `.../sit.py`, `.../sitdown.py`, `.../standup.py`, `.../stop.py`, `.../wave1.py`
- **Calibration/servo utility:**
- `servo.py` (90° set / calibration)

- **PCA9685 Servo Controller** (I2C target)
- **8x MG90 Servos** (PWM inputs)
- **3D Printed Frame & Legs** (from `3D Models/*.STL`, `Assembled Model.STL`)

- **Power subsystem** (battery/regulator) and separate rails
- **Operating system** on Pi (Ubuntu per README)
- **SSH service** on Pi (since remote execution is core)

##### Don’t overthink it: maximize components
For this repo, the “as many components as possible” interpretation is:
- Treat each motion file (`forward.py`, `sit.py`, etc.) as its own component (because each is a separately invoked behavior).
- Split “servo control” into two components:
- “Motion routine (angles over time)”
- “Driver/adapter to PCA9685 (I2C write)”
Even if the driver is embedded in the scripts today, showing it as a conceptual component makes the architecture clearer and more reusable.

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% View 1 — System Context / Deployment
%% =========================
subgraph "View 1 — System Context / Deployment"
direction TB

User["User (Operator)"]:::external

subgraph "Operator Device (Laptop/Desktop)"
direction TB
LocalConsole["mainl.py\nCommand Console / Remote Controller"]:::software
Paramiko["Paramiko\n(SSH client library)"]:::lib
end

WiFi["Wi‑Fi LAN"]:::network

subgraph "Robot Compute Plane (Raspberry Pi Zero W)"
direction TB
PiHW["Raspberry Pi Zero W\n(Ubuntu + Python)"]:::device
SSHd["SSH Service (sshd)"]:::service

subgraph "Robot-side Runtime Scripts\n(Code on Raspberry pi/)"
direction TB
Forward["forward.py\nForward Gait / Walk Routine"]:::software
Sit["sit.py\nSit Routine"]:::software
SitDown["sitdown.py\nSit-Down Routine"]:::software
StandUp["standup.py\nStand-Up Routine"]:::software
Stop["stop.py\nStop / Safety Halt Routine"]:::safety
Wave["wave1.py\nWave Routine"]:::software
end

ServoCal["servo.py\nServo Calibration (90° set)"]:::tool
I2CDriver["PCA9685 Driver/Adapter\n(I2C write commands)"]:::driver
end

subgraph "Actuation + Mechanics"
direction TB
PCA["PCA9685\nPWM Servo Controller"]:::electronics
Servos["8x MG90 Servos"]:::actuator

subgraph "3D Printed Frame & Legs"
direction TB
CADDir["3D Models/\nMechanical CAD/Print Artifacts"]:::mechanical
BaseSTL["base.STL"]:::mechanical
GapperSTL["gapper.STL"]:::mechanical
Leg12STL["leg1.2.STL"]:::mechanical
Leg2STL["leg2.STL"]:::mechanical
Leg3STL["leg3.STL"]:::mechanical
AssemblySTL["Assembled Model.STL\nFull Assembly"]:::mechanical
end
end

subgraph "Power Subsystem (separate rails + shared ground)"
direction TB
Power["Battery / 5V Supply + Regulators"]:::power
PiRail["5V Rail → Pi"]:::power
ServoRail["5V Rail → PCA9685 + Servos"]:::power
GND["Common GND"]:::power
end

Readme["README.md\nBuild/Usage Documentation"]:::doc
ExtNote["Extensibility:\nAdd new motion = add script in 'Code on Raspberry pi/'\n+ update command mapping in mainl.py"]:::note

end

%% Context connections
User -->|"enters_commands"| LocalConsole
LocalConsole -->|"uses"| Paramiko
Paramiko -->|"SSH(Paramiko)_over_Wi‑Fi"| WiFi
WiFi -->|"SSH_to_robot"| SSHd
SSHd -->|"executes_python_scripts"| Forward
SSHd -->|"executes_python_scripts"| Sit
SSHd -->|"executes_python_scripts"| SitDown
SSHd -->|"executes_python_scripts"| StandUp
SSHd -->|"executes_python_scripts"| Wave
SSHd -->|"executes_python_scripts"| Stop
SSHd -->|"executes_calibration"| ServoCal

PiHW --- SSHd
PiHW -->|"runs"| Forward
PiHW -->|"runs"| Sit
PiHW -->|"runs"| SitDown
PiHW -->|"runs"| StandUp
PiHW -->|"runs"| Wave
PiHW -->|"runs"| Stop
PiHW -->|"runs"| ServoCal

Forward -->|"angle_updates_over_time"| I2CDriver
Sit -->|"angle_updates_over_time"| I2CDriver
SitDown -->|"angle_updates_over_time"| I2CDriver
StandUp -->|"angle_updates_over_time"| I2CDriver
Wave -->|"angle_updates_over_time"| I2CDriver
Stop -->|"halt_pwm_updates"| I2CDriver
ServoCal -->|"set_all_to_90deg"| I2CDriver

I2CDriver -->|"I2C(SDA/SCL)"| PCA
PCA -->|"PWM_channels(x8)"| Servos
Servos -->|"mechanical_linkage_moves"| AssemblySTL

CADDir -->|"contains"| BaseSTL
CADDir -->|"contains"| GapperSTL
CADDir -->|"contains"| Leg12STL
CADDir -->|"contains"| Leg2STL
CADDir -->|"contains"| Leg3STL
CADDir -->|"used_to_build"| AssemblySTL

Readme -.->|"documents_setup"| LocalConsole
Readme -.->|"documents_SSH/Wi‑Fi"| SSHd
Readme -.->|"documents_build"| CADDir
ExtNote -.->|"guides_changes"| LocalConsole
ExtNote -.->|"guides_additions"| Forward

%% Power connections (separate style)
Power -->|"5V"| PiRail
Power -->|"5V"| ServoRail
Power -->|"GND"| GND
PiRail -->|"powers"| PiHW
ServoRail -->|"powers"| PCA
ServoRail -->|"powers"| Servos
GND -->|"shared_ground"| PiHW
GND -->|"shared_ground"| PCA
GND -->|"shared_ground"| Servos

%% =========================
%% View 2 — Runtime Control / Dataflow (command → gait execution)
%% =========================
subgraph "View 2 — Runtime Control / Dataflow"
direction TB

CmdIn["User Command\n(walk/sit/standup/wave/stop)"]:::external
Parse["mainl.py\nCommand parsing + mapping"]:::software
SSHExec["Paramiko\nSSH remote execution"]:::lib
SelectScript["Robot: choose motion script\n(forward/sit/standup/wave/stop)"]:::software
MotionLoop["Motion routine loop\n(set multiple joint angles over time)"]:::software
I2CWrite["I2C write to PCA9685\n(update PWM registers)"]:::driver
PWMOut["PCA9685 outputs PWM\nper channel"]:::electronics
Move["Servos move legs\npose/gait changes"]:::actuator
Safety["stop.py\nSafety halt path"]:::safety

CmdIn -->|"input"| Parse
Parse -->|"ssh_call"| SSHExec
SSHExec -->|"remote_command"| SelectScript
SelectScript -->|"starts"| MotionLoop
MotionLoop -->|"timed_steps"| I2CWrite
I2CWrite -->|"I2C(SDA/SCL)"| PWMOut
PWMOut -->|"PWM(x8)"| Move

Parse -->|"stop_command"| Safety
Safety -->|"halt_updates"| I2CWrite
end

%% =========================
%% View 3 — Hardware Interfaces (I2C vs PWM vs Power)
%% =========================
subgraph "View 3 — Hardware Interfaces"
direction TB

PiPins["Raspberry Pi Zero W\nGPIO: SDA/SCL + 5V/GND"]:::device
I2CBus["I2C Bus\n(SDA/SCL)"]:::network
PCAChip["PCA9685\nI2C target"]:::electronics
PWMSignals["PWM Signal Lines\n(8 channels)"]:::network
ServoBank["MG90 Servo Bank\n(8x)"]:::actuator
Mech["3D Printed Frame/Legs\n(Assembly)"]:::mechanical

Pwr3["Power Source"]:::power
Pi5["5V → Pi"]:::power
Servo5["5V → Servos/PCA9685"]:::power
Gnd3["GND (common)"]:::power

PiPins -->|"SDA/SCL"| I2CBus -->|"I2C"| PCAChip
PCAChip -->|"PWM_ch0..ch7"| PWMSignals -->|"signal"| ServoBank
ServoBank -->|"torque/motion"| Mech

Pwr3 -->|"5V"| Pi5 -->|"powers"| PiPins
Pwr3 -->|"5V"| Servo5 -->|"powers"| PCAChip
Pwr3 -->|"5V"| Servo5 -->|"powers"| ServoBank
Pwr3 -->|"GND"| Gnd3 -->|"common_ground"| PiPins
Gnd3 -->|"common_ground"| PCAChip
Gnd3 -->|"common_ground"| ServoBank
end

%% =========================
%% Click events (from component_mapping)
%% =========================
click LocalConsole "https://github.com/alenshaju12/toby/blob/main/mainl.py"
click Paramiko "https://github.com/alenshaju12/toby/blob/main/mainl.py"
click Forward "https://github.com/alenshaju12/toby/blob/main/Code on Raspberry pi/forward.py"
click Sit "https://github.com/alenshaju12/toby/blob/main/Code on Raspberry pi/sit.py"
click SitDown "https://github.com/alenshaju12/toby/blob/main/Code on Raspberry pi/sitdown.py"
click StandUp "https://github.com/alenshaju12/toby/blob/main/Code on Raspberry pi/standup.py"
click Stop "https://github.com/alenshaju12/toby/blob/main/Code on Raspberry pi/stop.py"
click Wave "https://github.com/alenshaju12/toby/blob/main/Code on Raspberry pi/wave1.py"
click ServoCal "https://github.com/alenshaju12/toby/blob/main/servo.py"
click CADDir "https://github.com/alenshaju12/toby/tree/main/3D Models/"
click BaseSTL "https://github.com/alenshaju12/toby/blob/main/3D Models/base.STL"
click GapperSTL "https://github.com/alenshaju12/toby/blob/main/3D Models/gapper.STL"
click Leg12STL "https://github.com/alenshaju12/toby/blob/main/3D Models/leg1.2.STL"
click Leg2STL "https://github.com/alenshaju12/toby/blob/main/3D Models/leg2.STL"
click Leg3STL "https://github.com/alenshaju12/toby/blob/main/3D Models/leg3.STL"
click AssemblySTL "https://github.com/alenshaju12/toby/blob/main/Assembled Model.STL"
click Readme "https://github.com/alenshaju12/toby/blob/main/README.md"

%% =========================
%% Styles
%% =========================
classDef external fill:#E6F0FF,stroke:#2B6CB0,stroke-width:2px,color:#0B1F44
classDef software fill:#D6E9FF,stroke:#1E5AA8,stroke-width:2px,color:#0B1F44
classDef lib fill:#CDEBFF,stroke:#0077B6,stroke-width:2px,color:#06334D
classDef device fill:#BFE3FF,stroke:#1D4ED8,stroke-width:2px,color:#071A3A
classDef service fill:#BBD7FF,stroke:#1E40AF,stroke-width:2px,color:#071A3A
classDef tool fill:#D7F3FF,stroke:#0284C7,stroke-width:2px,color:#06334D
classDef driver fill:#BDE7FF,stroke:#2563EB,stroke-width:2px,color:#071A3A
classDef electronics fill:#FFE6C7,stroke:#C2410C,stroke-width:2px,color:#3B1A00
classDef actuator fill:#D6F5D6,stroke:#15803D,stroke-width:2px,color:#062A12
classDef mechanical fill:#CFFAE5,stroke:#0F766E,stroke-width:2px,color:#042F2E
classDef safety fill:#FFD1D1,stroke:#B91C1C,stroke-width:2px,color:#3B0A0A
classDef power fill:#FFD0D0,stroke:#DC2626,stroke-width:2px,color:#3B0A0A
classDef network fill:#E0E7FF,stroke:#4338CA,stroke-width:2px,color:#111827
classDef doc fill:#F3F4F6,stroke:#6B7280,stroke-width:2px,color:#111827
classDef note fill:#FFF7CC,stroke:#A16207,stroke-width:2px,color:#3B2F00
```
