generated from wessel/boilerplate
Vincent W
5e1df5367c
Split documentation into three folders: Architecture, Testing and Installation. Rework and expand architecture.md alongside interfaces.md Split all parts to do with testing from Architecture md's into Test md's Add parameter to ExamResultGenerator node documentation
171 lines
4.6 KiB
Markdown
171 lines
4.6 KiB
Markdown
# 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
|
|
```
|
|
# Empty result section - completion indicates success
|
|
```
|
|
|
|
#### Feedback
|
|
```
|
|
float32 result
|
|
```
|
|
|
|
**Goal Fields**:
|
|
- `student_name`: Student for which a retake is requested
|
|
- `course_name`: Course for which a retake is requested
|
|
|
|
**Feedback Fields**:
|
|
- `result`: Progress indicator or intermediate result (float value)
|
|
|
|
**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 or re-enrolment
|
|
|
|
### 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
|
|
|
|
## Related Documentation
|
|
|
|
- [System Architecture](../Orig.md): Overall system design and communication patterns
|