generated from wessel/boilerplate
Major feat(Documentation): Complete documentation rework
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
This commit is contained in:
215
doc/architecture/Managers/ConfigManager.md
Normal file
215
doc/architecture/Managers/ConfigManager.md
Normal file
@@ -0,0 +1,215 @@
|
||||
# ConfigManager (`assignments::one::ConfigManager`)
|
||||
|
||||
## Overview
|
||||
|
||||
The `ConfigManager` class is used to be able to store configuration values in a `TOML` file making it
|
||||
possible to change project settings without the need of recompiling the codebase.
|
||||
|
||||
The [`toml++`](https://marzer.github.io/tomlplusplus/) library is used to parse TOML configuration
|
||||
files and provides type-safe access to configuration parameters. It is automatically installed
|
||||
using the `FetchContent_Declare` macro inside of the `CMakeLists.txt`.
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### Dependencies
|
||||
- **toml++**: Modern header-only C++17 TOML parser and serializer
|
||||
- **rclcpp**: ROS2 C++ client library for logging
|
||||
- **filesystem**: C++17 filesystem library for file operations
|
||||
- **DatabaseConfig**: Custom data structure for database configuration
|
||||
|
||||
### Key Components
|
||||
|
||||
#### Constructor
|
||||
```cpp
|
||||
ConfigManager(rclcpp::Logger logger)
|
||||
```
|
||||
- Initializes the configuration manager making use of a ROS2 logger
|
||||
- Calls `find_config_file()` and `load_config()` for automatic setup
|
||||
- Automatically attempts to locate and load configuration from a list of pre-defined paths.
|
||||
|
||||
#### Configuration Loading
|
||||
|
||||
**`bool load_config(const std::string& config_file_path)`**
|
||||
> Returns `true` on successful load, `false` on failure
|
||||
|
||||
- Uses `toml::parse_file()`
|
||||
- Loads TOML configuration from specified file path
|
||||
- Validates file existence before attempting to parse
|
||||
- Error handling for:
|
||||
- File not found errors
|
||||
- TOML parsing errors
|
||||
- General I/O exceptions
|
||||
- Updates internal `loaded_` state flag
|
||||
|
||||
**`std::string find_config_file() const`**
|
||||
> Returns first found configuration file path
|
||||
> Returns empty string if no configuration file is found
|
||||
|
||||
- Automatically searches for configuration files in predefined locations
|
||||
- Search paths (in order):
|
||||
```cpp
|
||||
std::vector<std::string> default_config_paths_ = {
|
||||
"config.toml",
|
||||
"./src/config.toml",
|
||||
"../config.toml",
|
||||
"../../config.toml",
|
||||
"../../../config.toml",
|
||||
"../../../../config.toml",
|
||||
"/etc/ros2_grade_calculator/config.toml"
|
||||
};
|
||||
```
|
||||
#### Configuration Access
|
||||
|
||||
**`std::optional<DatabaseConfig> get_database_config() const`**
|
||||
> Returns `std::optional<DatabaseConfig>` for safe null handling
|
||||
> Returns `std::nullopt` if:
|
||||
> - Configuration is not loaded
|
||||
> - Database section is missing
|
||||
> - Parsing fails due to invalid format
|
||||
|
||||
- Calls `parse_database_config()` for actual parsing
|
||||
|
||||
**`bool is_loaded() const`**
|
||||
> Returns `true` if configuration has been successfully loaded and parsed
|
||||
|
||||
- Getter for configuration load status
|
||||
- Used by other components to verify configuration availability
|
||||
|
||||
### Configuration Parsing
|
||||
|
||||
**`DatabaseConfig parse_database_config(const toml::table& config) const`**
|
||||
- parser for database configuration section
|
||||
- Extracts all database-related parameters with defaults
|
||||
|
||||
#### Default Values and Fallbacks
|
||||
- **host**: `"localhost"` - Local database server
|
||||
- **port**: `5432` - Standard PostgreSQL port
|
||||
- **dbname**: `"grades"` - Application-specific database
|
||||
- **user**: `"postgres"` - Default PostgreSQL user
|
||||
- **password**: `"postgres"` - Default PostgreSQL password
|
||||
- **timeout**: `30` seconds - connection timeout
|
||||
- **ssl**: `false` - Disabled by default for development
|
||||
- **min_connections**: `1` - Minimal connection pool
|
||||
- **max_connections**: `10` - connection pool limit
|
||||
|
||||
### Logging
|
||||
- Uses ROS2 logger with `[CFG]` prefix for configuration operations
|
||||
- Includes file paths in log messages
|
||||
|
||||
### Usage Examples
|
||||
|
||||
#### Automatic Configuration Loading
|
||||
```cpp
|
||||
// ConfigManager automatically finds and loads configuration
|
||||
ConfigManager config_manager(node->get_logger());
|
||||
|
||||
if (config_manager.is_loaded()) {
|
||||
auto db_config = config_manager.get_database_config();
|
||||
if (db_config.has_value()) {
|
||||
// Use database configuration
|
||||
DatabaseManager db_manager(db_config.value());
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Configuration File Format
|
||||
|
||||
Example complete TOML configuration:
|
||||
|
||||
```toml
|
||||
# Database connection settings
|
||||
[database]
|
||||
host = "localhost"
|
||||
port = 5432
|
||||
dbname = "grades"
|
||||
user = "postgres"
|
||||
password = "postgres"
|
||||
timeout = 30
|
||||
ssl = false
|
||||
|
||||
[database.pool]
|
||||
min_connections = 1
|
||||
max_connections = 10
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Unit Tests
|
||||
|
||||
Unit tests for `ConfigManager` are implemented in `src/g2_2025_grade_calculator_pkg/test/ConfigManager.test.cpp` using Google Test and ROS2 test utilities. The tests use temporary TOML files to validate configuration loading and parsing functionality.
|
||||
|
||||
### Test Cases
|
||||
|
||||
#### 1. ConstructorTest
|
||||
|
||||
**Description:** Verifies that ConfigManager can be created with a ROS2 logger without crashing.
|
||||
|
||||
- **Test Action:** Create ConfigManager instance with ROS2 logger
|
||||
- **Expected Result:** Instance created successfully without exceptions
|
||||
|
||||
#### 2. LoadValidConfigTest
|
||||
|
||||
**Description:** Tests loading of valid TOML configuration files with proper parsing.
|
||||
|
||||
- **Test Action:**
|
||||
- Create temporary TOML file with valid configuration
|
||||
- Call `load_config()` with file path
|
||||
- **Expected Result:**
|
||||
- Returns `true`
|
||||
- `is_loaded()` returns `true`
|
||||
|
||||
#### 3. LoadInvalidFileTest
|
||||
|
||||
**Description:** Tests error handling when attempting to load non-existent configuration files.
|
||||
|
||||
- **Test Action:** Call `load_config()` with non-existent file path
|
||||
- **Expected Result:**
|
||||
- Returns `false`
|
||||
- `is_loaded()` returns `false`
|
||||
|
||||
#### 4. DatabaseConfigParsingTest
|
||||
|
||||
**Description:** Tests complete database configuration parsing with all parameters.
|
||||
|
||||
- **Test Configuration:**
|
||||
```toml
|
||||
[database]
|
||||
host = "test_host"
|
||||
port = 1234
|
||||
dbname = "test_db"
|
||||
user = "test_user"
|
||||
password = "test_password"
|
||||
timeout = 60
|
||||
ssl = true
|
||||
|
||||
[database.pool]
|
||||
min_connections = 2
|
||||
max_connections = 20
|
||||
```
|
||||
- **Expected Result:** All configuration values parsed correctly with proper types
|
||||
|
||||
#### 5. DatabaseConfigWithoutPoolTest
|
||||
|
||||
**Description:** Tests default values when optional pool section is missing from configuration.
|
||||
|
||||
- **Test Configuration:**
|
||||
```toml
|
||||
[database]
|
||||
host = "localhost"
|
||||
port = 5432
|
||||
dbname = "grades"
|
||||
user = "postgres"
|
||||
password = "postgres"
|
||||
```
|
||||
- **Expected Result:**
|
||||
- Main database config parsed correctly
|
||||
- Default pool values: `min_connections = 1`, `max_connections = 10`
|
||||
|
||||
#### 6. GetConfigWithoutLoadingTest
|
||||
|
||||
**Description:** Tests behavior when attempting to access configuration before loading any file.
|
||||
|
||||
- **Test Action:** Call `get_database_config()` without loading configuration
|
||||
- **Expected Result:**
|
||||
- Returns `std::nullopt`
|
||||
- `is_loaded()` returns `false`
|
||||
191
doc/architecture/Managers/DatabaseManager.md
Normal file
191
doc/architecture/Managers/DatabaseManager.md
Normal file
@@ -0,0 +1,191 @@
|
||||
# DatabaseManager (`assignments::one::DatabaseManager`)
|
||||
|
||||
## Overview
|
||||
|
||||
The `DatabaseManager` class is a PostgreSQL database interface for the ROS2 grade calculator.
|
||||
It handles all database operations including connection management, table creation and data insertion.
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### Dependencies
|
||||
- **pqxx**: Modern C++ PostgreSQL library for database connectivity
|
||||
- **rclcpp**: ROS2 C++ client library for logging
|
||||
- **ConfigManager**: Configuration manager for database settings
|
||||
|
||||
### Key Components
|
||||
|
||||
#### Constructor
|
||||
```cpp
|
||||
DatabaseManager(rclcpp::Logger logger)
|
||||
```
|
||||
- Initializes the database manager with ROS2 logging
|
||||
- Creates a ConfigManager instance for configuration handling
|
||||
- Automatically calls `init_database()` to establish connection and setup
|
||||
|
||||
#### Connection Management
|
||||
|
||||
**`bool connect(const std::string& connection_string)`**
|
||||
> Returns `true` on successful connection, `false` on failure
|
||||
|
||||
- Establishes connection to PostgreSQL database using connection information from the config TOML
|
||||
- Connection string format: `"host=localhost port=5432 dbname=grades user=postgres password=postgres"`
|
||||
|
||||
**`bool is_connected() const`**
|
||||
> Returns `true` if connection exists and is open
|
||||
|
||||
- Check for active database connection status
|
||||
|
||||
#### Database Initialization
|
||||
|
||||
**`void init_database()`**
|
||||
- Database setup process
|
||||
- Loads configuration from ConfigManager
|
||||
- Establishes connection using configuration settings
|
||||
- Creates necessary tables and inserts sample data
|
||||
- Error handling for configuration and connection failures
|
||||
|
||||
**`void create_tables()`**
|
||||
- Creates all required database tables using SQL queries from `SQLQueries.hpp`
|
||||
- Tables created:
|
||||
- `enrollments`: Student course enrollments
|
||||
- `exam_results`: Individual exam scores
|
||||
- `course_results`: Final course grades and statistics
|
||||
- Uses transactions for atomic table creation
|
||||
|
||||
**`void insert_sample_data()`**
|
||||
- Inserts predefined sample student data
|
||||
|
||||
### Data Operations
|
||||
|
||||
#### Student Course Management
|
||||
|
||||
**`std::vector<StudentCourse> queue_pending_combinations()`**
|
||||
> Returns vector of StudentCourse objects for processing queue
|
||||
|
||||
- Gets all student-course combinations that need exam results generated
|
||||
- Executes complex SQL query to find missing exam results
|
||||
|
||||
**`bool enroll_student_into_course(const StudentCourse& sc)`**
|
||||
> Returns `true` on successful enrollment, `false` on failure
|
||||
|
||||
- Enrolls a student into a specific course
|
||||
|
||||
#### Exam Result Processing
|
||||
|
||||
**`bool store_exam_result(const std::string& student_name, const std::string& course_name, int grade)`**
|
||||
- Stores individual exam results in the database
|
||||
- Parameters:
|
||||
- `student_name`: Name of the student
|
||||
- `course_name`: Name of the course
|
||||
- `grade`: Exam score (10-100)
|
||||
|
||||
**`bool store_final_course_result(const StudentCourse& sc, int exam_count, int final_grade)`**
|
||||
- Stores calculated final course results
|
||||
- Parameters:
|
||||
- `sc`: StudentCourse object containing student and course names
|
||||
- `exam_count`: Number of exams taken
|
||||
- `final_grade`: Calculated final grade
|
||||
- Used by grade calculation nodes for final result storage
|
||||
|
||||
#### Grade Retrieval
|
||||
|
||||
**`int get_final_course_grade(const StudentCourse& sc)`**
|
||||
> Returns:
|
||||
> - `> 0`: Valid final grade (rounded average)
|
||||
> - `-1`: No exams taken or no results found
|
||||
|
||||
- Gets final calculated grade for a student-course combination
|
||||
- Performs average calculation with proper rounding
|
||||
- Used by nodes to check if final grading is complete
|
||||
|
||||
### Logging
|
||||
|
||||
- Uses ROS2 logger with `[DBS]` prefix for database operations
|
||||
- Different log levels:
|
||||
- `INFO`: Successful operations, connection status
|
||||
- `ERROR`: SQL errors, connection failures, configuration issues
|
||||
- `WARN`: Non-critical issues, missing configurations
|
||||
|
||||
|
||||
### Usage Examples
|
||||
|
||||
#### Basic Database Setup
|
||||
```cpp
|
||||
// Create DatabaseManager with ROS2 logger
|
||||
DatabaseManager db_manager(node->get_logger());
|
||||
|
||||
// Check connection status
|
||||
if (db_manager.is_connected()) {
|
||||
// Database ready for operations
|
||||
bool success = db_manager.store_exam_result("Wessel", "ROS2", 85);
|
||||
if (success) {
|
||||
RCLCPP_INFO(logger, "Exam result stored successfully");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Unit Tests
|
||||
|
||||
Unit tests for `DatabaseManager` are implemented in `src/g2_2025_grade_calculator_pkg/test/DatabaseManager.test.cpp` using Google Test and ROS2 test utilities. The tests are designed to work reliably whether a database connection is available or not, focusing on error handling and method behavior validation.
|
||||
|
||||
### Test Cases
|
||||
|
||||
#### 1. ConstructorTest
|
||||
|
||||
**Description:** Verifies that DatabaseManager can be created without crashing and proper initialization occurs.
|
||||
|
||||
- **Test Action:** Create DatabaseManager instance with ROS2 logger
|
||||
- **Expected Result:** Instance created successfully without exceptions
|
||||
|
||||
#### 2. ConnectionStatusTest
|
||||
|
||||
**Description:** Tests that the `is_connected()` method returns a valid boolean value.
|
||||
|
||||
- **Test Action:** Call `is_connected()` method
|
||||
- **Expected Result:** Returns either `true` or `false` (no crashes or invalid states)
|
||||
|
||||
#### 3. QueuePendingCombinationsTest
|
||||
|
||||
**Description:** Verifies retrieval of pending student-course combinations that need exam results.
|
||||
|
||||
- **Test Action:** Call `queue_pending_combinations()`
|
||||
- **Expected Result:** Returns valid vector (empty if no database connection, populated if connected)
|
||||
|
||||
#### 4. StoreExamResultTest
|
||||
|
||||
**Description:** Tests exam result storage with graceful handling of connection states.
|
||||
|
||||
- **Test Action:**
|
||||
- Student: `"TestStudent"`
|
||||
- Course: `"TestCourse"`
|
||||
- Grade: `85`
|
||||
- **Expected Result:** Returns `false` if no connection, `true` if connected and successful
|
||||
|
||||
#### 5. EnrollStudentTest
|
||||
|
||||
**Description:** Tests student enrollment into courses.
|
||||
|
||||
- **Test Action:**
|
||||
- StudentCourse object with test data
|
||||
- **Expected Result:** Returns `false` if no connection, `true` if connected and successful
|
||||
|
||||
#### 6. GetFinalGradeTest
|
||||
|
||||
**Description:** Tests final grade retrieval for non-existent student-course combinations.
|
||||
|
||||
- **Test Action:**
|
||||
- Student: `"NonExistentStudent"`
|
||||
- Course: `"NonExistentCourse"`
|
||||
- **Expected Result:** Returns `-1` (no results found or no connection)
|
||||
|
||||
#### 7. StoreFinalResultTest
|
||||
|
||||
**Description:** Tests storing calculated final course results.
|
||||
|
||||
- **Test Action:**
|
||||
- StudentCourse object
|
||||
- Exam count: `3`
|
||||
- Final grade: `75`
|
||||
- **Expected Result:** Returns `false` if no connection, `true` if connected and successful
|
||||
147
doc/architecture/architecture.md
Normal file
147
doc/architecture/architecture.md
Normal file
@@ -0,0 +1,147 @@
|
||||
# TI Minor Grade Generator Design Document
|
||||
|
||||
## Project Overview
|
||||
|
||||
The TI Minor Grade Generator is a distributed ROS2-based system designed to manage student exam results and calculate final course grades. The system follows microservices architecture principles with clear separation of concerns and robust data management.
|
||||
|
||||
## System Architecture
|
||||
|
||||
### High-Level Architecture
|
||||
|
||||
The system consists of multiple ROS2 nodes that communicate through standardized topics and services to process exam data, calculate grades, and persist results. The architecture ensures scalability, maintainability, and fault tolerance.
|
||||
|
||||
### Key Design Principles
|
||||
|
||||
- **Microservices Architecture**: Each component has a single responsibility
|
||||
- **Asynchronous Communication**: Uses ROS2 topics and services for loose coupling
|
||||
- **Data Persistence**: Centralized database management for reliable storage
|
||||
- **Configurable Parameters**: TOML-based configuration for environment flexibility
|
||||
- **Comprehensive Testing**: Unit and integration tests ensure reliability
|
||||
|
||||
## System Components
|
||||
|
||||
### Core Nodes
|
||||
|
||||
#### 1. FinalGradeDeterminator Node
|
||||
**Namespace**: `assignments::one::final_grade_determinator`
|
||||
|
||||
**Brief Description**: Collects exam results, triggers grade calculation when thresholds are met, and stores final grades.
|
||||
|
||||
**Key Features**: Configurable collection thresholds, automatic grade calculation triggering, database persistence
|
||||
|
||||
*For detailed documentation, see: [FinalGradeDeterminator.md](nodes/FinalGradeDeterminator.md)*
|
||||
|
||||
#### 2. GradeCalculator Node
|
||||
**Namespace**: `assignments::one::grade_calculator`
|
||||
|
||||
**Brief Description**: Provides grade calculation service with business logic including bonus points and grade validation.
|
||||
|
||||
**Key Features**: Average calculation, special student rules, grade bounds validation (10-100)
|
||||
|
||||
*For detailed documentation, see: [GradeCalculator.md](nodes/GradeCalculator.md)*
|
||||
|
||||
#### 3. ExamResultGenerator Node
|
||||
**Namespace**: `assignments::one::exam_result_generator`
|
||||
|
||||
**Brief Description**: Simulates exam result generation by maintaining a queue of student-course combinations and publishing random grades.
|
||||
|
||||
**Key Features**: Database-driven queue management, random grade generation, student enrollment handling
|
||||
|
||||
*For detailed documentation, see: [ExamResultGenerator.md](nodes/ExamResultGenerator.md)*
|
||||
|
||||
#### 4. RetakeScheduler Node
|
||||
**Namespace**: `assignments::one::retake_scheduler`
|
||||
|
||||
**Brief Description**: Manages retake exam scheduling and coordination for students who need to retake exams.
|
||||
|
||||
**Key Features**: Retake request processing, schedule management, action server implementation for retake workflows
|
||||
|
||||
*For detailed documentation, see: [RetakeScheduler.md](nodes/RetakeScheduler.md)*
|
||||
|
||||
#### 5. RetakeGradeDeterminator Node
|
||||
**Namespace**: `assignments::one::retake_grade_determinator`
|
||||
|
||||
**Brief Description**: Handles grade calculation and processing specifically for retake exams.
|
||||
|
||||
**Key Features**: Retake-specific grade processing, integration with main grade system, retake result validation
|
||||
|
||||
*For detailed documentation, see: [RetakeGradeDeterminator.md](nodes/RetakeGradeDeterminator.md)*
|
||||
|
||||
### Data Management
|
||||
|
||||
#### DatabaseManager
|
||||
**Brief Description**: PostgreSQL database interface handling connections, table management, and data persistence.
|
||||
|
||||
**Key Features**: Connection management, automatic table creation, student enrollment tracking, exam result storage
|
||||
|
||||
*For detailed documentation, see: [DatabaseManager.md](../DatabaseManager.md)*
|
||||
|
||||
#### ConfigManager
|
||||
**Brief Description**: TOML-based configuration management system allowing runtime configuration without recompilation.
|
||||
|
||||
**Key Features**: Automatic config file discovery, type-safe TOML parsing, database connection configuration
|
||||
|
||||
*For detailed documentation, see: [ConfigManager.md](../ConfigManager.md)*
|
||||
|
||||
### Communication Interfaces
|
||||
|
||||
#### ROS2 Message and Service Interfaces
|
||||
**Brief Description**: Custom message types and service definitions for inter-node communication.
|
||||
|
||||
**Key Components**: Exam and Student message types, Grade calculation service, Retake action interface, standardized timestamps
|
||||
|
||||
*For detailed documentation, see: [interfaces.md](interfaces/interfaces.md)*
|
||||
|
||||
## System Workflow
|
||||
|
||||
### 1. Exam Result Processing
|
||||
|
||||
1. **Input**: Exam results are published to the `exam_results` topic
|
||||
2. **Collection**: FinalGradeDeterminator receives and stores exam results by student-course combination
|
||||
3. **Monitoring**: System tracks the number of results per student-course pair
|
||||
4. **Threshold Check**: When `grade_collection_amount` results are collected, proceed to calculation
|
||||
|
||||
### 2. Grade Calculation Process
|
||||
|
||||
1. **Service Request**: FinalGradeDeterminator calls GradeCalculator service
|
||||
2. **Calculation**: GradeCalculator computes final grade using business logic
|
||||
3. **Validation**: Result is validated and clamped to acceptable range
|
||||
4. **Response**: Calculated grade is returned to FinalGradeDeterminator
|
||||
|
||||
### 3. Result Management
|
||||
|
||||
1. **Database Storage**: Final grade is persisted in the database
|
||||
2. **Publication**: Student information is published to management topic
|
||||
3. **Logging**: Process completion is logged for audit purposes
|
||||
|
||||
### 4. Retake Processing Workflow
|
||||
|
||||
1. **Retake Request**: RetakeScheduler receives retake requests via action interface
|
||||
2. **Schedule Management**: System schedules retake exams and manages timelines
|
||||
3. **Retake Execution**: Student completes retake exam, results are processed
|
||||
4. **Grade Processing**: RetakeGradeDeterminator calculates retake grades with specialized logic
|
||||
5. **Integration**: Retake results are integrated with main grade system and database
|
||||
|
||||
## Configuration Management
|
||||
|
||||
### TOML Configuration Structure
|
||||
|
||||
The system uses TOML files for environment-specific configuration:
|
||||
|
||||
```toml
|
||||
[database]
|
||||
host = "localhost"
|
||||
port = 5432
|
||||
name = "grade_db"
|
||||
user = "grade_user"
|
||||
password = "secure_password"
|
||||
|
||||
[grade_calculation]
|
||||
collection_amount = 5
|
||||
min_grade = 10
|
||||
max_grade = 100
|
||||
|
||||
[logging]
|
||||
level = "INFO"
|
||||
output_file = "grade_system.log"
|
||||
```
|
||||
170
doc/architecture/interfaces/interfaces.md
Normal file
170
doc/architecture/interfaces/interfaces.md
Normal file
@@ -0,0 +1,170 @@
|
||||
# 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
|
||||
43
doc/architecture/nodes/ExamResultGenerator.md
Normal file
43
doc/architecture/nodes/ExamResultGenerator.md
Normal file
@@ -0,0 +1,43 @@
|
||||
# ExamResultGenerator (`assignments::one::exam_result_generator`)
|
||||
|
||||
## Overview
|
||||
The `ExamResultGenerator` is the core node responsible for simulating exam result generation.
|
||||
It maintains a queue of student-course combinations that need exam results, generates random
|
||||
grades, and publishes them to the system.
|
||||
|
||||
#### Implementation Details
|
||||
|
||||
**Parameters**
|
||||
|
||||
- **`delay_between_grades_ms`** (int, default: 2000): Delay (in milliseconds) between generated grades.
|
||||
|
||||
**Constructor**
|
||||
```cpp
|
||||
ExamResultGenerator()
|
||||
```
|
||||
- Initializes ROS2 node with name `exam_result_generator`
|
||||
- Sets up random number generation infrastructure
|
||||
- Creates DatabaseManager instance with node logger
|
||||
- Establishes ROS2 publishers, subscribers, and timers
|
||||
- Loads initial pending combinations from database
|
||||
|
||||
**Core Functions**
|
||||
|
||||
**`void queue_pending_combinations()`**
|
||||
- Gets all student-course combinations needing exam results
|
||||
- Populates operations queue from database
|
||||
- Called at initialization and when database state changes
|
||||
|
||||
**`void generate_random_result()`**
|
||||
- Main exam result generation executed by timer
|
||||
- Selects random student-course combination from queue
|
||||
- Stores result in database and publishes to ROS2 topic
|
||||
|
||||
**`void student_management_callback(const g2_2025_interfaces::msg::Student::SharedPtr msg)`**
|
||||
- Toggles combinations in/out of processing queue
|
||||
- Updates database with new enrollments
|
||||
|
||||
**`void add_student_course_combination(const StudentCourse& sc)`**
|
||||
- Enrolls student into course via database
|
||||
- Adds combination to processing queue
|
||||
|
||||
42
doc/architecture/nodes/FinalGradeDeterminator.md
Normal file
42
doc/architecture/nodes/FinalGradeDeterminator.md
Normal file
@@ -0,0 +1,42 @@
|
||||
# FinalGradeDeterminator (`assignments::one::final_grade_determinator`)
|
||||
|
||||
## Overview
|
||||
The `FinalGradeDeterminator` node collects exam results for student-course combinations, triggers grade calculation when enough results are gathered, and stores final grades in the database. It interacts with ROS2 publishers, subscribers, and service clients to manage the grading workflow.
|
||||
|
||||
#### Implementation Details
|
||||
|
||||
**Parameters**
|
||||
|
||||
- **`grade_collection_amount`** (int, default: 5): Number of exam results required before triggering grade calculation for a student-course combination.
|
||||
|
||||
**Constructor**
|
||||
```cpp
|
||||
FinalGradeDeterminator()
|
||||
```
|
||||
- Initializes ROS2 node with name `final_grade_determinator`
|
||||
- Declares and retrieves `grade_collection_amount` parameter
|
||||
- Sets up `DatabaseManager`
|
||||
- Creates publisher for student course management
|
||||
- Subscribes to exam results topic
|
||||
- Initializes service client for grade calculation
|
||||
|
||||
**Core Functions**
|
||||
|
||||
**`void exam_results_callback(const g2_2025_interfaces::msg::Exam::SharedPtr msg)`**
|
||||
- Updates internal map with received exam result for student-course combo
|
||||
- Checks if enough results have been collected
|
||||
- Triggers grade calculation request when threshold is met
|
||||
|
||||
**`void grade_calculator_request(StudentCourse combo)`**
|
||||
- Waits for grade calculator service to be available
|
||||
- Sends async request with collected exam grades for the student-course combination
|
||||
- Uses callback to handle service response
|
||||
|
||||
|
||||
**`void grade_calculator_response(rclcpp::Client<g2_2025_interfaces::srv::Exams>::SharedFuture future, StudentCourse studentCourseCombo)`**
|
||||
- Verifies database connection
|
||||
- Publishes final student message to ROS2 topic
|
||||
- Logs final grade information
|
||||
- Stores final course result in database
|
||||
|
||||
|
||||
25
doc/architecture/nodes/GradeCalculator.md
Normal file
25
doc/architecture/nodes/GradeCalculator.md
Normal file
@@ -0,0 +1,25 @@
|
||||
# GradeCalculator (`assignments::one::grade_calculator::GradeCalculator`)
|
||||
|
||||
## Overview
|
||||
The `GradeCalculator` node provides a ROS2 service for calculating student exam grades. It processes exam scores, applies custom logic for specific student names, and ensures grade results are within valid bounds.
|
||||
|
||||
#### Implementation Details
|
||||
|
||||
**Constructor**
|
||||
```cpp
|
||||
GradeCalculator()
|
||||
```
|
||||
- Initializes ROS2 node with name `grade_calculator`
|
||||
- Creates a ROS2 service server for `grade_calculator_service`
|
||||
- Binds the service callback to handle grade calculation requests
|
||||
- Logs service startup
|
||||
|
||||
**Core Functions**
|
||||
|
||||
**`void grade_calculator_callback(const Exams::Request::SharedPtr request, const Exams::Response::SharedPtr response)`**
|
||||
- Checks if exam grades are provided
|
||||
- Calculates the total and average of exam grades
|
||||
- Converts student name to lowercase for comparison
|
||||
- Adds a bonus of 10 points if the student name is "wessel"
|
||||
- Ensures the final grade is clamped between 10 and 100
|
||||
- Sends the calculated grade back through the service response
|
||||
Reference in New Issue
Block a user