# j-y-001/mtrn3100_thur architecture

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

- Interactive diagram: https://gitdiagram.com/j-y-001/mtrn3100_thur
- Repository: https://github.com/j-y-001/mtrn3100_thur

## Overview

This repository is an Arduino/embedded robotics codebase organized as a set of **standalone sketches** for different lab stages or robot behaviors, rather than one single application. The root README is minimal, but the file tree shows a clear pattern: each activity has its own `.ino` entry point and a small set of reusable control/sensing headers.

1. **Primary runtime model**
   - The main execution units are Arduino sketches such as `MTRN3100_Thur.ino`, `3.1_Driving.ino`, `Turning.ino`, `Continuous.ino`, and `Chaining.ino`.
   - Each sketch appears to be a self-contained robot program with its own control loop, hardware setup, and behavior logic.

2. **Shared hardware abstraction layer**
   - Several reusable headers define the core robot interfaces:
     - `Motor.hpp`
     - `DualEncoder.hpp`
     - `PIDController.hpp`
     - `EncoderOdometry.hpp`
     - `IMUOdometry.hpp`
   - These likely form the low-level stack for motor control, wheel feedback, and pose estimation.

3. **Motion control subsystem**
   - `Motor.hpp` is the actuator layer, likely wrapping PWM/direction control for the drive motors.
   - `PIDController.hpp` provides feedback control, presumably used to regulate wheel speed, heading, or trajectory following.
   - This is the main control boundary between high-level behavior and hardware actuation.

4. **Sensing and state estimation**
   - `DualEncoder.hpp` represents wheel encoder input from a differential-drive robot.
   - `EncoderOdometry.hpp` and `IMUOdometry.hpp` are two alternative pose-estimation paths:
     - encoder-based odometry for dead reckoning
     - IMU-based orientation/pose support
   - These components likely feed the control loops in the motion sketches.

5. **Behavior-specific sketches**
   - `3.1_Driving/`, `Turning/`, `Continuous/`, and `Chaining/` each contain a sketch plus local copies of the same core headers.
   - That structure suggests the project is organized around incremental milestones:
     - driving straight
     - turning accurately
     - continuous/path motion
     - chaining multiple movements or waypoints

6. **Path data and trajectory-following**
   - `path.h`, `path_c.h`, `Chaining/path.h`, and `Continuous/path_c.h` indicate static path definitions embedded in firmware.
   - These files likely store waypoints, headings, or command sequences used by the robot to execute preplanned motion rather than interactive control.

7. **Duplicated headers across folders**
   - The same names appear both at the repository root and inside individual experiment folders.
   - Architecturally, this suggests each sketch was developed as an isolated package, with local copies of the supporting classes to keep experiments independent and easier to compile in the Arduino IDE.

8. **Peripheral demos / side experiments**
   - The `New folder/` directory contains separate demos unrelated to the main drive-control stack:
     - `SSD1306_HelloWorldWire` for an OLED display
     - `twoLidar` and `twoLidarWithSSD1306` for lidar sensing, with and without display output
   - These are likely sensor/peripheral integration tests that sit alongside the robot-control work.

9. **Notebook-based analysis and testing**
   - Several `.ipynb` notebooks exist (`test.ipynb`, `part2.ipynb`, `Chaining/test.ipynb`, `Continuous/part2.ipynb`).
   - These likely serve as offline analysis, path generation, or experiment documentation rather than firmware runtime components.

10. **Repository boundary**
   - There is no sign of a server, GUI app, or cloud dependency.
   - The architecture is entirely firmware-centric: Arduino sketches consume sensor data, compute odometry/control, and drive motors directly on embedded hardware.

11. **Likely data flow**
   - Hardware inputs: encoders, IMU, and in some demos lidar/display peripherals.
   - Processing: odometry and PID/control logic.
   - Outputs: motor commands, and optionally display/debug information.
   - For path-based sketches, preloaded path data flows into the controller as a sequence of motion targets.

12. **How to diagram it**
   - The cleanest architecture view would show:
     - multiple independent sketch entry points
     - a shared cluster of control/sensing modules
     - optional path-data inputs
     - hardware peripherals at the edges
   - The main distinction is between the **drive-control stack** and the **peripheral demo stack**.

In short, this repo is a collection of Arduino robot-control experiments built around a reusable differential-drive control pipeline, with separate sketches for progressively more advanced motion behaviors and a few unrelated sensor/display demos.

Main entry points: [`Turning/Turning.ino`](https://github.com/j-y-001/mtrn3100_thur/blob/main/Turning/Turning.ino) (Turning), [`Chaining/Chaining.ino`](https://github.com/j-y-001/mtrn3100_thur/blob/main/Chaining/Chaining.ino) (Chaining), [`Motor.hpp`](https://github.com/j-y-001/mtrn3100_thur/blob/main/Motor.hpp) (Motor), [`DualEncoder.hpp`](https://github.com/j-y-001/mtrn3100_thur/blob/main/DualEncoder.hpp) (Encoders)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Drive sketches"]
  node_n1["Main sketch<br/>arduino sketch<br/>[MTRN3100_Thur.ino]"]
  node_n2["Driving<br/>arduino sketch<br/>[3.1_Driving.ino]"]
  node_n3["Turning<br/>arduino sketch<br/>[Turning.ino]"]
  node_n4["Continuous<br/>arduino sketch<br/>[Continuous.ino]"]
  node_n5["Chaining<br/>arduino sketch<br/>[Chaining.ino]"]
  node_n11["Path data<br/>trajectory data<br/>[path.h]"]
  node_n12["Path data C<br/>trajectory data<br/>[path_c.h]"]
end

subgraph group_g2["Shared stack"]
  node_n6["Motor<br/>actuator wrapper<br/>[Motor.hpp]"]
  node_n7["Encoders<br/>wheel sensors<br/>[DualEncoder.hpp]"]
  node_n8["PID control<br/>feedback controller<br/>[PIDController.hpp]"]
  node_n9["Encoder odom<br/>pose estimation"]
  node_n10["IMU odom<br/>pose estimation<br/>[IMUOdometry.hpp]"]
end

subgraph group_g3["Peripheral demos"]
  node_n13["OLED demo<br/>display sketch"]
  node_n14["Two lidar<br/>sensor sketch<br/>[twoLidar.ino]"]
  node_n15["Lidar + OLED<br/>sensor sketch"]
end

subgraph group_g4["Offline work"]
  node_n16["Test notebook<br/>analysis notebook<br/>[test.ipynb]"]
  node_n17["Part 2 notebook<br/>analysis notebook<br/>[part2.ipynb]"]
  node_n18["Chain notebook<br/>analysis notebook<br/>[test.ipynb]"]
end

node_n1 -->|"drives"| node_n6
node_n1 -->|"reads"| node_n7
node_n1 -->|"controls"| node_n8
node_n2 -->|"drives"| node_n6
node_n2 -->|"reads"| node_n7
node_n2 -->|"controls"| node_n8
node_n3 -->|"drives"| node_n6
node_n3 -->|"reads"| node_n7
node_n3 -->|"controls"| node_n8
node_n3 -->|"estimates"| node_n9
node_n3 -->|"estimates"| node_n10
node_n4 -->|"drives"| node_n6
node_n4 -->|"reads"| node_n7
node_n4 -->|"controls"| node_n8
node_n4 -->|"follows"| node_n12
node_n5 -->|"drives"| node_n6
node_n5 -->|"reads"| node_n7
node_n5 -->|"controls"| node_n8
node_n5 -->|"follows"| node_n11
node_n5 -->|"follows"| node_n12
node_n13 -.->|"shares peripherals"| node_n14
node_n14 -.->|"extends"| node_n15

click node_n1 "https://github.com/j-y-001/mtrn3100_thur/blob/main/MTRN3100_Thur.ino"
click node_n2 "https://github.com/j-y-001/mtrn3100_thur/blob/main/3.1_Driving/3.1_Driving.ino"
click node_n3 "https://github.com/j-y-001/mtrn3100_thur/blob/main/Turning/Turning.ino"
click node_n4 "https://github.com/j-y-001/mtrn3100_thur/blob/main/Continuous/Continuous.ino"
click node_n5 "https://github.com/j-y-001/mtrn3100_thur/blob/main/Chaining/Chaining.ino"
click node_n6 "https://github.com/j-y-001/mtrn3100_thur/blob/main/Motor.hpp"
click node_n7 "https://github.com/j-y-001/mtrn3100_thur/blob/main/DualEncoder.hpp"
click node_n8 "https://github.com/j-y-001/mtrn3100_thur/blob/main/PIDController.hpp"
click node_n9 "https://github.com/j-y-001/mtrn3100_thur/blob/main/EncoderOdometry.hpp"
click node_n10 "https://github.com/j-y-001/mtrn3100_thur/blob/main/IMUOdometry.hpp"
click node_n11 "https://github.com/j-y-001/mtrn3100_thur/blob/main/path.h"
click node_n12 "https://github.com/j-y-001/mtrn3100_thur/blob/main/path_c.h"
click node_n13 "https://github.com/j-y-001/mtrn3100_thur/blob/main/New folder/SSD1306_HelloWorldWire/SSD1306_HelloWorldWire.ino"
click node_n14 "https://github.com/j-y-001/mtrn3100_thur/blob/main/New folder/twoLidar/twoLidar.ino"
click node_n15 "https://github.com/j-y-001/mtrn3100_thur/blob/main/New folder/twoLidarWithSSD1306/twoLidarWithSSD1306.ino"
click node_n16 "https://github.com/j-y-001/mtrn3100_thur/blob/main/test.ipynb"
click node_n17 "https://github.com/j-y-001/mtrn3100_thur/blob/main/part2.ipynb"
click node_n18 "https://github.com/j-y-001/mtrn3100_thur/blob/main/Chaining/test.ipynb"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n1,node_n2,node_n3,node_n4,node_n5,node_n11,node_n12 toneBlue
class node_n6,node_n7,node_n8,node_n9,node_n10 toneAmber
class node_n13,node_n14,node_n15 toneMint
class node_n16,node_n17,node_n18 toneRose
```

## Components

### Drive sketches

Standalone robot behaviors and motion labs

- [Main sketch](https://github.com/j-y-001/mtrn3100_thur/blob/main/MTRN3100_Thur.ino): arduino sketch · Top-level robot entry point · `MTRN3100_Thur.ino`
- [Driving](https://github.com/j-y-001/mtrn3100_thur/blob/main/3.1_Driving/3.1_Driving.ino): arduino sketch · Straight-line drive milestone · `3.1_Driving/3.1_Driving.ino`
- [Turning](https://github.com/j-y-001/mtrn3100_thur/blob/main/Turning/Turning.ino): arduino sketch · Turn control behavior · `Turning/Turning.ino`
- [Continuous](https://github.com/j-y-001/mtrn3100_thur/blob/main/Continuous/Continuous.ino): arduino sketch · Continuous motion behavior · `Continuous/Continuous.ino`
- [Chaining](https://github.com/j-y-001/mtrn3100_thur/blob/main/Chaining/Chaining.ino): arduino sketch · Multi-step motion sequences · `Chaining/Chaining.ino`
- [Path data](https://github.com/j-y-001/mtrn3100_thur/blob/main/path.h): trajectory data · Embedded waypoint and command sequences · `path.h`
- [Path data C](https://github.com/j-y-001/mtrn3100_thur/blob/main/path_c.h): trajectory data · Embedded path definitions for continuous/chaining behaviors · `path_c.h`

### Shared stack

Reusable control, sensing, and estimation modules

- [Motor](https://github.com/j-y-001/mtrn3100_thur/blob/main/Motor.hpp): actuator wrapper · Drive motor control interface · `Motor.hpp`
- [Encoders](https://github.com/j-y-001/mtrn3100_thur/blob/main/DualEncoder.hpp): wheel sensors · Dual encoder input and tick handling · `DualEncoder.hpp`
- [PID control](https://github.com/j-y-001/mtrn3100_thur/blob/main/PIDController.hpp): feedback controller · Closed-loop motion regulation · `PIDController.hpp`
- [Encoder odom](https://github.com/j-y-001/mtrn3100_thur/blob/main/EncoderOdometry.hpp): pose estimation · Dead-reckoning from wheel encoders · `EncoderOdometry.hpp`
- [IMU odom](https://github.com/j-y-001/mtrn3100_thur/blob/main/IMUOdometry.hpp): pose estimation · Orientation and pose support from IMU · `IMUOdometry.hpp`

### Peripheral demos

Independent sensor and display experiments

- [OLED demo](https://github.com/j-y-001/mtrn3100_thur/blob/HEAD/New%20folder/SSD1306_HelloWorldWire/SSD1306_HelloWorldWire.ino): display sketch · SSD1306 hello-world example · `New folder/SSD1306_HelloWorldWire/SSD1306_HelloWorldWire.ino`
- [Two lidar](https://github.com/j-y-001/mtrn3100_thur/blob/HEAD/New%20folder/twoLidar/twoLidar.ino): sensor sketch · Dual-lidar experiment · `New folder/twoLidar/twoLidar.ino`
- [Lidar + OLED](https://github.com/j-y-001/mtrn3100_thur/blob/HEAD/New%20folder/twoLidarWithSSD1306/twoLidarWithSSD1306.ino): sensor sketch · Dual-lidar plus display integration · `New folder/twoLidarWithSSD1306/twoLidarWithSSD1306.ino`

### Offline work

Notebooks and analysis artifacts

- [Test notebook](https://github.com/j-y-001/mtrn3100_thur/blob/main/test.ipynb): analysis notebook · Offline experiment notes or analysis · `test.ipynb`
- [Part 2 notebook](https://github.com/j-y-001/mtrn3100_thur/blob/main/part2.ipynb): analysis notebook · Offline work for later lab stages · `part2.ipynb`
- [Chain notebook](https://github.com/j-y-001/mtrn3100_thur/blob/main/Chaining/test.ipynb): analysis notebook · Offline work for chaining behavior · `Chaining/test.ipynb`

## Connections

- Main sketch → Motor: drives · Uses motor interface for actuation
- Main sketch → Encoders: reads · Consumes wheel encoder feedback
- Main sketch → PID control: controls · Applies feedback control
- Driving → Motor: drives · Controls the motors
- Driving → Encoders: reads · Uses encoders for motion feedback
- Driving → PID control: controls · Uses PID for motion regulation
- Turning → Motor: drives · Controls the motors
- Turning → Encoders: reads · Uses encoders for turn feedback
- Turning → PID control: controls · Uses PID for heading control
- Turning → Encoder odom: estimates · May use encoder-based pose estimates
- Turning → IMU odom: estimates · May use IMU-based orientation support
- Continuous → Motor: drives · Controls the motors
- Continuous → Encoders: reads · Uses encoders for closed-loop motion
- Continuous → PID control: controls · Uses PID for continuous regulation
- Continuous → Path data C: follows · Consumes embedded path data
- Chaining → Motor: drives · Controls the motors
- Chaining → Encoders: reads · Uses encoders for feedback
- Chaining → PID control: controls · Uses PID for segment execution
- Chaining → Path data: follows · Consumes embedded path data
- Chaining → Path data C: follows · Consumes embedded path data
- OLED demo → Two lidar: shares peripherals · Both are standalone hardware demos
- Two lidar → Lidar + OLED: extends · Display-enhanced variant of the lidar demo
