How j-y-001/mtrn3100_thur works
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.ino Turning · Chaining.ino Chaining · Motor.hpp Motor · DualEncoder.hpp Encoders
Components 18
Drive sketches
Standalone robot behaviors and motion labs
- Main sketch · Top-level robot entry point
MTRN3100_Thur.ino - Driving · Straight-line drive milestone
3.1_Driving/3.1_Driving.ino - Turning · Turn control behavior
Turning/Turning.ino - Continuous · Continuous motion behavior
Continuous/Continuous.ino - Chaining · Multi-step motion sequences
Chaining/Chaining.ino - Path data · Embedded waypoint and command sequences
path.h - Path data C · Embedded path definitions for continuous/chaining behaviors
path_c.h
Shared stack
Reusable control, sensing, and estimation modules
- Motor · Drive motor control interface
Motor.hpp - Encoders · Dual encoder input and tick handling
DualEncoder.hpp - PID control · Closed-loop motion regulation
PIDController.hpp - Encoder odom · Dead-reckoning from wheel encoders
EncoderOdometry.hpp - IMU odom · Orientation and pose support from IMU
IMUOdometry.hpp
Peripheral demos
Independent sensor and display experiments
- OLED demo · SSD1306 hello-world example
New folder/SSD1306_HelloWorldWire/SSD1306_HelloWorldWire.ino - Two lidar · Dual-lidar experiment
New folder/twoLidar/twoLidar.ino - Lidar + OLED · Dual-lidar plus display integration
New folder/twoLidarWithSSD1306/twoLidarWithSSD1306.ino
Offline work
Notebooks and analysis artifacts
- Test notebook · Offline experiment notes or analysis
test.ipynb - Part 2 notebook · Offline work for later lab stages
part2.ipynb - Chain notebook · Offline work for chaining behavior
Chaining/test.ipynb
Connections 22
- 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