# ROS2 Interface Definitions - g2_2025_interfaces

## Package Overview

This document describes the custom ROS2 interface definitions in the `g2_2025_interfaces` package. These interfaces provide standardized communication protocols for the TI Minor Grade Generator system.

**Package Name**: `g2_2025_interfaces`
**Interface Types**: Messages, Services, Actions
**Location**: `src/g2_2025_interfaces/`

## Message Types (.msg)

### Exam.msg

Represents examination result data exchanged between system components.

```
string student_name
string course_name
int32 result
builtin_interfaces/Time timestamp
```

**Field Descriptions**:
- `student_name`: Name identifier for the student
- `course_name`: Course identifier for the examination
- `result`: Numerical exam result/grade (integer value)
- `timestamp`: Timestamp of the message

**Usage**: Primary message type for exam result communication between ExamResultGenerator and grade processing nodes.

### Student.msg

Represents student information and course enrollment data.

```
string student_name
string course_name
builtin_interfaces/Time timestamp
```

**Field Descriptions**:
- `student_name`: Name identifier for the student
- `course_name`: Course identifier for enrollment/management
- `timestamp`: Timestamp of the message

**Usage**: Used for student-course management operations and enrollment tracking.

## Service Definitions (.srv)

### Exams.srv

Service interface for grade calculation operations using multiple exam results.

#### Request
```
string student_name
string course_name
int32[] exam_grades
```

#### Response
```
int32 result  # Final calculated result
```

**Request Fields**:
- `student_name`: Student identifier for grade calculation
- `course_name`: Course identifier for context
- `exam_grades`: Array of exam grades to be processed

**Response Fields**:
- `result`: Final calculated grade result (integer value)

**Usage**: Main service interface used by GradeCalculator node for processing multiple exam grades into final results.

## Action Definitions (.action)

### Retake.action

Action interface for managing retake exam scheduling and processing workflows.

#### Goal
```
string student_name
string course_name
```

#### Result
```
float32 result
```

#### Feedback
```
string status
```

**Goal Fields**:
- `student_name`: Student for which a retake is requested
- `course_name`: Course for which a retake is requested

**Result Field**
- `result`: Progress indicator or intermediate result (float value) (*Not Implemented*)

**Feedback Field**:
- `status`: Status indicator (*Not Implemented*)

**Usage**: Used by RetakeScheduler node to handle long-running retake management operations with progress feedback.

## Node Interface Usage

### ExamResultGenerator Node

**Publishers**:
- **Topic**: `exam_results`
- **Message Type**: `g2_2025_interfaces::msg::Exam`
- **Purpose**: Publishes generated exam results to downstream processing nodes
- **Rate**: Configurable interval (default: 2 seconds)

**Subscribers**:
- **Topic**: `student_course_management`
- **Message Type**: `g2_2025_interfaces::msg::Student`
- **Purpose**: Receives student-course enrollment updates for exam generation queue

### FinalGradeDeterminator Node

**Subscribers**:
- **Topic**: `exam_results`
- **Message Type**: `g2_2025_interfaces::msg::Exam`
- **Purpose**: Collects exam results for grade calculation processing

**Service Clients**:
- **Service**: `calculate_grade`
- **Service Type**: `g2_2025_interfaces::srv::Exams`
- **Purpose**: Requests grade calculation from GradeCalculator when threshold is met

**Publishers**:
- **Topic**: `student_course_management`
- **Message Type**: `g2_2025_interfaces::msg::Student`
- **Purpose**: Communicate end of enrollment when grade has been calculated

### GradeCalculator Node

**Service Servers**:
- **Service**: `calculate_grade`
- **Service Type**: `g2_2025_interfaces::srv::Exams`
- **Purpose**: Provides grade calculation services for multiple exam grades
- **Processing**: Applies business logic (averaging, bonus points, validation)

### RetakeScheduler Node

**Action Servers**:
- **Action**: `retake_request`
- **Action Type**: `g2_2025_interfaces::action::Retake`
- **Purpose**: Handles long-running retake scheduling operations
- **Feedback**: Provides progress updates during scheduling process

### RetakeGradeDeterminator Node

**Service Clients**:
- **Service**: `calculate_grade`
- **Service Type**: `g2_2025_interfaces::srv::Exams`
- **Purpose**: Requests specialized retake grade calculations

**Subscribers**:
- **Topic**: `retake_results`
- **Message Type**: `g2_2025_interfaces::msg::Exam`
- **Purpose**: Processes completed retake exam results