gPBL: Control System Design with Arduino and MATLAB

This repository contains all project files, source code, experiment data, and reports for the 2025 Online global Project Based-Learning (gPBL) program on Power System Control Training , hosted by Shibaura Institute of Technology (SIT).

This project involves practical experiments based on the textbook "Control System Design: Getting Started with Arduino and MATLAB". The primary goal is to bridge control theory with hands-on application using Model-Based Design (MBD).

Partner Universities:

• Shibaura Institute of Technology (SIT), Japan
• Ho Chi Minh City University of Technology (HCMUT), Vietnam
• Hanoi University of Science and Technology (HUST), Vietnam
• Institut Teknologi Bandung (ITB), Indonesia
• Thai-Nichi Institute of Technology (TNI), Thailand

---

Repository Structure

This repository is organized to separate code, data, and documentation clearly.

├── .gitignore # Files for Git to ignore (MATLAB temp files, etc.) 
├── LICENSE # Project license (MIT) 
├── README.md # This file 
├── docs/ # Setup guides, hardware diagrams, and datasheets 
├── data/ # Raw and processed data from experiments 
├── src/ # All MATLAB (.m) and Simulink (.mdl) source code 
└── reports/ # Weekly reports and final presentations

---

🚀 Getting Started

Follow these steps to set up the project environment on your local machine.

Prerequisites

Hardware:

• Arduino Mega 2560 R3
• Custom Motor/Servo Kit (for Chapters 4, 5)
• Ball & Beam Kit (for Chapters 6, 7)

Software:

• MATLAB/Simulink (R2021b or newer)
• Required Toolboxes:
  • Control System Toolbox
  • Simulink
  • MATLAB Coder / Simulink Coder (for RoTH)
• Arduino IDE (for drivers and setup)
• ArduinoIO Library (for communication with Simulink)

Installation

1. Clone the repository:

   git clone [https://github.com/your-username/gPBL-Control-System-Design-Arduino-MATLAB.git](https://github.com/your-username/gPBL-Control-System-Design-Arduino-MATLAB.git)
   cd gPBL-Control-System-Design-Arduino-MATLAB

2. Set up the Environment:
   • Follow the detailed instructions in docs/setup_guide.md.
   • Install the required MATLAB Toolboxes.
   • Install the ArduinoIO library and upload the adiosrv.pde sketch to your Arduino.
3. Set MATLAB Path:
   • Open MATLAB.
   • Add the src/ directory and all its subfolders to the MATLAB path.
   • Run src/lib/sim_init.m to initialize workspace variables and parameters.

---

🔬 How to Use

Each chapter's experiments are self-contained in the src/ folder.

1. Navigate to the desired chapter, e.g., src/chapter_05_motor_position_control/.
2. Ensure your hardware is connected as shown in docs/hardware_setup.md.
3. Open the corresponding Simulink model (e.g., pos_pid_mbd_s1.mdl).
4. Run the simulation. Experimental data will be saved to the corresponding data/ folder.

Key Project Files

• src/chapter_05_motor_position_control/pos_pid_mbd_s1.mdl: PID control design for motor position using Pole Assignment.
• src/chapter_07_modern_control_theory/bb_lqr_hg_s1.mdl: Optimal State Feedback (LQR) control for the Ball & Beam system.
• src/chapter_08_run_on_target_hardware/bbt_pid_hg_s1.mdl: Real-time PID controller running directly on the Arduino Mega (RoTH).

---

⚡ Automated One-Click Setup & Diagnostics

To get started quickly without manual path setting:

• Inside MATLAB (All Operating Systems & Versions):

  >> setup

  Automatically validates toolboxes, registers search paths, scans connected Arduino hardware, and initializes parameters (sim_param.mat).

• From Terminal (macOS / Linux):

  ./setup.sh

• From Windows Command Prompt / PowerShell:

  setup.bat
  # or in PowerShell:
  .\setup.ps1

• System Self-Test Diagnostic Suite:

  >> report = check_environment();

• 🛠️ Experiment Template Generator (Zero-Python Scaffolder): Quickly scaffold a standardized, production-ready Model-Based Design sandbox (parameters, programmatic Simulink model builder, hardware runner, unit test suite, and experiment README) in one step:

  • Inside MATLAB (All Platforms):

    >> init_template('my_speed_exp', 'speed')       % 1st-Order Speed Control (Ch. 4)
    >> init_template('my_pos_exp', 'position')     % 2nd-Order Position Control (Ch. 5)
    >> init_template('my_bnb_exp', 'ball_beam')    % Ball & Beam Double Integrator (Ch. 6)
    >> init_template('my_lqr_exp', 'state_space')  % Modern LQR/LQI State Feedback (Ch. 7)
    >> init_template                               % Interactive prompt mode

  • From Terminal (macOS / Linux):

    ./tools/init_template.sh -n my_speed_exp -t speed

  • From Windows Command Prompt / PowerShell:

    tools\init_template.bat -n my_speed_exp -t speed
    # or in PowerShell:
    .\tools\init_template.ps1 -Name my_speed_exp -Type speed

---

📚 Technical Documentation & Guides

Document	Topic & Focus	Target Audience
docs/setup_guide.md	Step-by-step software, toolbox, and firmware upload guide	All Users
docs/hardware_setup.md	Wiring schematics, TA7291P driver, PSD sensor, and mechanical assembly	Hardware Labs
docs/cross_platform_guide.md	Windows, macOS (Apple Silicon/Intel), and Linux setup & USB optimizations	Cross-Platform Users
docs/matlab_version_compatibility.md	Compatibility matrix for MATLAB R2012a through R2024b+	All MATLAB Versions
docs/arduino_compatibility_guide.md	Arduino IDE (1.8.x & 2.x), Mega 2560 vs Uno, and clone drivers (CH340)	Microcontroller Setup
docs/troubleshooting.md	Comprehensive dictionary of error messages, causes, and verified fixes	Troubleshooting

---

📋 Complete Chapter & MATLAB Program Registry

Chapter	Focus & System	Key MATLAB Programs (.m)	Key Simulink Models (.mdl)
Ch. 3: Arduino I/O	Digital/Analog I/O, PWM, RC Servo	led_blink.m, led_blink2.m, sw_count.m, rc_servo.m	led_blink_sl.mdl, led_blink2_sl.mdl, a_read_sl.mdl, rc_servo_sl.mdl
Ch. 4: Speed Control	DC Motor 1st-Order Lag ($K_v=1.57, T_v=0.76$)	velo_id_gain.m, velo_id_tc.m, velo_id_verify.m, velo_pi_mbd.m	velo_test.mdl, velo_p.mdl, velo_pi.mdl, velo_pi_mbd_sl.mdl
Ch. 5: Position Control	DC Motor 2nd-Order ($K=365, T=0.32$)	second_sys.m, pos_id_step.m, pos_id_step_fit.m, pos_pid_mbd.m, pid_compare.m, pos_pid2_mbd.m, ipd_ff.m, pos_tdof_mbd.m	pos_id_step_sl.mdl, pos_pid_mbd_sl.mdl, pos_pid2_mbd_sl.mdl, pos_tdof_mbd_sl.mdl
Ch. 6: Ball & Beam	Unstable Double Integrator ($K_b=588$)	psd_test.m, psd_plot.m, bb_pid_rc.m, bb_pid_hg.m	bb_pid_rc_sl.mdl, bb_pid_hg_sl.mdl
Ch. 7: Modern Control	4th-Order State-Space LQR & LQI Servo	bb_lqr_test.m (LQR Riccati), bb_lqr_servo_hg.m (LQI Optimal Servo)	bb_lqr_hg_sl.mdl, bb_lqr_servo_hg_sl.mdl
Ch. 8: RoTH Standalone	Native C++ Deployment on Microcontroller	bbt_pid_hg.m, bbt_lqr_hg.m, bbt_lqr_servo_hg.m	bbt_pid_hg_sl.mdl, bbt_lqr_hg_sl.mdl

---

🔄 CI/CD & Automated Workflows

This repository incorporates automated GitHub Actions quality gates and release distribution:

• Continuous Integration (.github/workflows/ci.yml):
  • Static Audit & Zero-Python Enforcement: Ensures 0 Python scripts in src/ and tools/ for guaranteed pure MATLAB simulation performance.
  • Syntax & Delimiter Balance: Audits delimiter balance ((), [], {}) across all MATLAB files and validates shell syntax (bash -n).
  • Cross-Platform Matrix: Tests setup tools and template scaffolder across Ubuntu Linux, macOS (Darwin), and Windows.
  • Attribution & CFF Integrity: Validates ATTRIBUTION.md, CITATION.cff, and license notices on every pull request and push.
• Automated Release Packager (.github/workflows/release.yml):
  • Triggers on version tags (v*.*.*) to publish GitHub Releases with standalone archives:
    • Complete Source Code Bundle (gPBL-Control-System-Design-*-full.zip)
    • Standalone Arduino Firmware (gPBL-Arduino-Firmware-*.zip)
    • Simulink Models & Calibration Data (gPBL-Simulink-Models-and-Data-*.zip)
    • Cryptographic SHA-256 Checksums (checksums.sha256)

---

License

This project is licensed under the MIT License. See the LICENSE file for details.

📖 Academic Attribution & Copyright Notice

For comprehensive institutional credits, copyright details, and legal notices, see ATTRIBUTION.md and CITATION.cff.

• Foundational Textbook: Control System Design: Getting Started with Arduino and MATLAB (『ArduinoとMATLABで始める制御システム設計』) by Prof. Goro Fujita, Department of Electrical Engineering, Shibaura Institute of Technology (SIT), Tokyo, Japan. Published by Tokyo Denki University Press.
• Program Host: 2025 Online global Project-Based Learning (gPBL) on Power System Control Training, hosted by Shibaura Institute of Technology (SIT).
• Personal Educational Work: Software implementations, programmatic builders, and automated tools independently authored by Nguyen Trong Thang (Ho Chi Minh City University of Technology — HCMUT).
• Fair-Use Notice: Theoretical concepts, plant parameters, and algorithm schemas are included strictly for non-commercial educational training and scientific study under 17 U.S.C. § 107, Japanese Copyright Law Art. 32/35, and Vietnamese IP Law Art. 25.

BibTeX Citation

@book{fujita_arduino_matlab,
  author    = {Goro Fujita},
  title     = {Control System Design: Getting Started with Arduino and MATLAB (ArduinoとMATLABで始める制御システム設計)},
  publisher = {Tokyo Denki University Press},
  year      = {2014},
  address   = {Tokyo, Japan}
}

@software{thang_gpbl_control_2025,
  author       = {Nguyen Trong Thang},
  title        = {gPBL Control System Design with Arduino and MATLAB},
  year         = {2025},
  publisher    = {GitHub},
  url          = {https://github.com/ntthang-dev/gPBL-Control-System-Design-Arduino-MATLAB}
}

Acknowledgments

• Prof. Goro Fujita and the Power System Lab at SIT.
• Co-organizer: Elysa Nensy Irawan.
• TA: Castillo Efrain.
• All fellow participants and faculty from HCMUT, HUST, ITB, and TNI.

---

Notes for SIT Partners (SITの皆様へ)

Click here to read the project description in Japanese (日本語でのプロジェクト概要はこちらをクリックしてください)

プロジェクト概要

このリポジトリは、芝浦工業大学（SIT）主催のオンラインgPBL「電力系統制御トレーニング」のプロジェクトファイルです。

ホーチミン市工科大学（HCMUT）の学生として、教科書「ArduinoとMATLABで始める制御システム設計」に基づき、MATLAB/SimulinkとArduinoを用いたモデルベースデザイン（MBD）の実践に取り組んでいます。

ご指導のほど、よろしくお願いいたします。