VE-Lab Hardware Autograder

Hệ thống chấm điểm tự động cho các bài thực hành lập trình nhúng trên vi điều khiển STM32.

Sinh viên push code (main.c) lên GitHub → hệ thống tự động biên dịch, nạp xuống phần cứng thật, bắt tín hiệu số thực tế trên bus (I2C / SPI / UART / PWM / 1-Wire) bằng Logic Analyzer, rồi chấm điểm dựa trên dữ liệu đo được — thay cho việc chấm tay từng bài.

---

1. Ý tưởng

Mỗi bài lab yêu cầu sinh viên lập trình một ngoại vi STM32 (GPIO, UART, Timer, SPI, I2C, DS1307, DHT11). Thay vì giảng viên nạp và soi từng board, hệ thống dùng:

• 1 board "Student" — chạy firmware của sinh viên.
• 1 board "Simulator" — chạy firmware giả lập cảm biến/thiết bị ngoại vi (DS1307, DHT11…) để tương tác với board Student.
• Logic Analyzer — bắt lại toàn bộ khung tín hiệu giữa 2 board rồi so khớp với đáp án.

Toàn bộ chạy trên một Raspberry Pi đóng vai trò GitHub self-hosted runner.

2. Quy trình chấm (pipeline)

1. Build — biên dịch firmware Student và Simulator.
2. Flash — nạp stu.hex / sim.hex xuống 2 board qua ST-Link.
3. Register Check — đọc trực tiếp thanh ghi ngoại vi của board Student qua SWD (pyOCD) để kiểm tra cấu hình.
4. Logic Capture — nhả reset cho 2 board chạy, dùng sigrok bắt tín hiệu bus → result.csv.
5. Grade — so khớp result.csv với các test case trong file cấu hình JSON của bài lab.

Sơ đồ tuần tự chi tiết (đầy đủ Phase 1–4; các bước Matrix/UART là kiến trúc mục tiêu, đang triển khai):

3. Phần cứng

Thiết bị	Vai trò
Raspberry Pi 4B	Self-hosted runner, điều phối toàn bộ quy trình
2× STM32F103RCT6	Board Student + board Simulator
2× ST-Link V2	Nạp firmware & đọc thanh ghi (SWD)
Logic Analyzer 8 kênh (fx2lafw)	Bắt tín hiệu I2C/SPI/UART/PWM/DHT

Sơ đồ trên là kiến trúc mục tiêu. Hiện Student ↔ Simulator nối dây trực tiếp; ma trận chuyển mạch CH446Q + UART backchannel đang được triển khai.

4. Công nghệ sử dụng

• Firmware: C, STM32 SPL, FreeRTOS (board Simulator), arm-none-eabi-gcc.
• Autograder: Python 3 — st-flash, pyOCD, sigrok-cli, libgpiod v2.
• CI: GitHub Actions self-hosted runner.

5. Cấu trúc thư mục

ve_lab/
├── assignments/     # Cau hinh cac bai lab (lab1_gpio.json ... lab7_dht11.json)
├── firmware/
│   ├── student/     # Template firmware sinh vien          -> build/stu.hex
│   └── simulator/   # Firmware gia lap (FreeRTOS, layered)  -> build/sim.hex
├── grader/          # Autograder Python (main, builder, capture, check_reg, check_logic)
├── docs/            # Tai lieu he thong + huong dan cai dat (SETUP.md)
├── reference/       # Bo quy tac code (coding/commit/layer style)
├── toolchain/       # ARM GCC (x86_64) de build local
└── setup.sh         # Script cai dat toan bo moi truong tren Pi

6. Bắt đầu

• Cài đặt từ đầu trên Pi: xem docs/SETUP.md — hoặc chạy thẳng ./setup.sh.
• Chạy chấm một bài lab:

  python3 grader/main.py --lab lab6_ds1307

  Chạy từng phase riêng bằng cờ --build / --flash / --reg / --capture / --grade.

7. Tài liệu

Tài liệu	Nội dung
docs/SETUP.md	Cài đặt môi trường từ đầu → chạy được
reference/_index.md	Bộ quy tắc code cho firmware
AGENTS.md	Context cho AI agent (tiếng Anh)