Skip to content

AutomaticGrader

Automated checker for SE 423 (UIUC) homework and lab firmware. Compiles student code written for the TI C2000 (TMS320F28379D LaunchPad) against Linux stubs, drives the patched main() cooperatively from a single thread, and grades the submission by inspecting simulated peripheral register state plus captured serial_printf output.

Designed to slot into a course CI/CD pipeline as a reusable GitHub Actions workflow so submissions are graded automatically before they reach Gradescope.

Where to start

  • Run it locally

    Install dependencies, build for one assignment, run the grader on a reference fixture.

    Getting started

  • Add a new checker

    Step-by-step from a fresh assignment spec to a passing hw{N}.cpp with a green CI run.

    Contributor tutorial

  • Understand the architecture

    Three-layer model, cooperative main-loop driver, capture pipeline, and the four-phase check pattern.

    Architecture overview

  • Wire it into a course repo

    Reusable workflow setup, manifest format, duplicate-id submissions, and per-folder report traceability.

    CI/CD workflow

What the grader does, in one diagram

flowchart LR
    Spec["HW#123;N#125;.tex<br>Lab#123;N#125;.txt"]
    Student["Student firmware<br>workspace/&lt;folder&gt;"]
    Patcher["patch_student_source.py"]
    Driver["Cooperative<br>main-loop driver"]
    Checker["hw#123;N#125;.cpp /<br>lab#123;N#125;.cpp"]
    Stubs["TI peripheral<br>stubs + capture"]
    Report["Markdown +<br>JSON report"]

    Spec -.authoritative.-> Checker
    Student --> Patcher --> Driver
    Driver <--> Stubs
    Checker <--> Stubs
    Checker --> Report

    classDef src fill:#dbeafe,stroke:#2563eb
    classDef harness fill:#fef3c7,stroke:#d97706
    classDef out fill:#dcfce7,stroke:#16a34a
    class Spec,Student src
    class Patcher,Driver,Stubs,Checker harness
    class Report out

Authority hierarchy

  1. Spec is absolute. Every checker assertion must trace to a quoted sentence in context/homeworks/HW{N}.tex or context/lab/Lab{N}.txt.
  2. Where the spec is ambiguous, tag the assertion [ambiguous] in the assignment roadmap and pick the most common interpretation.
  3. Reference solutions are non-authoritative. They inform stub design and serve as one positive-test fixture. Where they deviate from the spec, the spec wins and the reference is allowed to fail.

Repository status

The full per-assignment implementation matrix lives in the CLAUDE.md file and the roadmap files under progress/. Skim those when planning a new checker — they encode the validation matrix (mutation testing, snapshot hygiene, regression) you'll be held to.