generated from wessel/boilerplate
feat(readme): Add aditional content to the main readme
This commit is contained in:
118
README.md
118
README.md
@@ -10,3 +10,121 @@ Assignments made for the first semester of ROS2
|
|||||||
<br><br>
|
<br><br>
|
||||||
|
|
||||||
## Table of contents
|
## Table of contents
|
||||||
|
|
||||||
|
- [System Architecture](#system-architecture)
|
||||||
|
- [Components](#components)
|
||||||
|
- [Installation](#installation)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## System Architecture
|
||||||
|
|
||||||
|
The TI Minor Grade Generator is a ROS2-based distributed system for managing student exam results and calculating final grades. The system follows a microservices architecture with clear separation of concerns.
|
||||||
|
|
||||||
|
### Overview
|
||||||
|
|
||||||
|
The system consists of multiple ROS2 nodes that communicate through topics and services to process exam data, calculate grades, and store the results in a database.
|
||||||
|
|
||||||
|
### Components
|
||||||
|
|
||||||
|
#### Core Nodes
|
||||||
|
|
||||||
|
1. **ExamResultGenerator** (`assignments::one::exam_resutl_generator`)
|
||||||
|
- Publishes random exam results for students and courses
|
||||||
|
- Simulates exam result generation for testing and demonstration
|
||||||
|
- ([Full documentation](doc/nodes/ExamResultGenerator))
|
||||||
|
|
||||||
|
|
||||||
|
2. **FinalGradeDeterminator** (`assignments::one::final_grade_determinator`)
|
||||||
|
- Collect grades from ExamResultGenerator
|
||||||
|
- Send results to the GradeCalculator
|
||||||
|
- Put resulting grade in the Database
|
||||||
|
- ([Full documentation](doc/nodes/FinalGradeDeterminator))
|
||||||
|
|
||||||
|
3. **GradeCalculator** (`assignments::one::grade_calculator`)
|
||||||
|
- Provides ROS2 service for calculating student exam grades
|
||||||
|
- Ensures grade results are within valid bounds (10-100)
|
||||||
|
- ([Full documentation](doc/nodes/GradeCalculator))
|
||||||
|
|
||||||
|
|
||||||
|
#### Database Management
|
||||||
|
|
||||||
|
- **DatabaseManager**: Handles all database operations including storing final course results
|
||||||
|
- ([Full documentation](doc/DatabaseManager.md))
|
||||||
|
|
||||||
|
#### Configuration Management
|
||||||
|
|
||||||
|
- **ConfigManager**: Loads and validates system configuration from TOML files
|
||||||
|
- Provides runtime access to configuration parameters for all nodes
|
||||||
|
- Ensures consistent environment setup and error handling for misconfigurations
|
||||||
|
- ([Full documentation](doc/ConfigManager.md))
|
||||||
|
|
||||||
|
#### Message Interfaces
|
||||||
|
|
||||||
|
- **Exam Messages** (`g2_2025_interfaces::msg::Exam`): Contains student name, course name, result, and timestamp
|
||||||
|
- **Student Messages** (`g2_2025_interfaces::msg::Student`): Contains student and course information with timestamp
|
||||||
|
- **Grade Calculation Service** (`g2_2025_interfaces::srv::Exams`): Service interface for grade calculation requests
|
||||||
|
|
||||||
|
### Workflow
|
||||||
|
|
||||||
|
1. **Exam Result Collection**: Exam results are published to the `exam_results` topic
|
||||||
|
2. **Result Aggregation**: FinalGradeDeterminator collects results until the configured threshold is met
|
||||||
|
3. **Grade Calculation**: When enough results are available, a service call is made to GradeCalculator
|
||||||
|
4. **Result Processing**: Calculated grades are published and stored in the database
|
||||||
|
5. **Student Management**: Final student information is published to `student_course_management` topic as this stops the random generation of grades
|
||||||
|
6. **Retake scheduler**: Schedule an exam retake for the grades below 55 by resending information to `student_course_management` as this will re-enable grade generation
|
||||||
|
7. **Retake grade determination**: repeat steps 1 through 6 using the `retake_grade_determinator` node instead of `final_grade_determinator` until every student hase a passing grade
|
||||||
|
|
||||||
|
### Configuration
|
||||||
|
|
||||||
|
The system uses TOML configuration files for environment-specific settings:
|
||||||
|
- Database connection parameters
|
||||||
|
- ROS2 node configurations
|
||||||
|
- Grade collection thresholds
|
||||||
|
|
||||||
|
### Testing
|
||||||
|
|
||||||
|
Unit tests are implemented using Google Test framework:
|
||||||
|
- Mock services and database managers for isolated testing
|
||||||
|
- Parameterized tests for various grade calculation scenarios
|
||||||
|
- Documentation on the tests are located in the full documentation of the nodes themselves
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
### Prerequisites
|
||||||
|
|
||||||
|
- ROS2 Jazzy or newer installed ([ROS2 Installation Guide](https://docs.ros.org/en/jazzy/Installation.html))
|
||||||
|
- CMake (version 3.8+)
|
||||||
|
- Python 3.8+
|
||||||
|
- libtomlplusplus-dev
|
||||||
|
- libpqxx-dev
|
||||||
|
- Colcon build tool
|
||||||
|
- Docker compose
|
||||||
|
|
||||||
|
### Clone the Repository
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone https://git.wessel.gg/inholland/ros2-assignments.git
|
||||||
|
cd ros2-assignments
|
||||||
|
```
|
||||||
|
|
||||||
|
### Build the Workspace
|
||||||
|
|
||||||
|
```bash
|
||||||
|
colcon build
|
||||||
|
```
|
||||||
|
Any parameters can be changed before building by editing the `grade_calculator.launch.xml` in the launch folder
|
||||||
|
|
||||||
|
### Source the Workspace
|
||||||
|
|
||||||
|
```bash
|
||||||
|
source install/setup.bash
|
||||||
|
```
|
||||||
|
|
||||||
|
### Run the System
|
||||||
|
|
||||||
|
```bash
|
||||||
|
sudo docker-compose up
|
||||||
|
ros2 launch g2_2025_grade_calculator_pkg grade_calculator.launch.xml
|
||||||
|
```
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user