diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md new file mode 100644 index 0000000..618ba18 --- /dev/null +++ b/DOCUMENTATION.md @@ -0,0 +1,49 @@ +# Documentation of Current State 2024 + +## Overview + +This document provides a detailed overview of the purpose of each area in the service robot and the technologies used. It includes examples of each ROS node's purpose and a detailed example of a task flow for the `receptionist_task_manager.py` node. + +## Purpose of Each Area + +### Human-Robot Interaction (HRI) +The HRI area focuses on enabling the robot to interact effectively with humans. It includes tasks such as speaking, guest information retrieval, and guest analysis. The `hri_tasks.py` node manages the implementation of HRI tasks. + +### Manipulation +The manipulation area focuses on enabling the robot to perform tasks that involve manipulating objects. It includes tasks such as picking, placing, and moving arm joints. The `manipulation_tasks.py` node manages the implementation of manipulation tasks. + +### Navigation +The navigation area focuses on enabling the robot to move to specific locations and store the current location. The `nav_tasks.py` node manages the implementation of navigation tasks. + +### Vision +The vision area focuses on enabling the robot to process visual information and interact with its environment. It includes tasks such as saving face names, checking for persons, and finding free seats. The `vision_tasks.py` node manages the implementation of vision tasks. + +## Examples of ROS Nodes Purpose + +* `receptionist_task_manager.py` (`ws/src/frida_task_manager/scripts/receptionist_task_manager.py`): Manages the receptionist task, including guest interaction, face recognition, and navigation to the living room. +* `breakfast_task_manager.py` (`ws/src/frida_task_manager/scripts/breakfast_task_manager.py`): Manages the breakfast task, including picking and placing objects, pouring, and navigating to different locations. +* `demo_tmr24.py` (`ws/src/frida_task_manager/scripts/demo_tmr24.py`): Demonstrates the task manager for the breakfast task, including guest interaction, face recognition, and serving breakfast. +* `task_manager_server.py` (`ws/src/frida_task_manager/scripts/task_manager_server.py`): Serves as a template for developing multiple task managers for various tasks in RoboCup@Home. +* `hri_tasks.py` (`ws/src/frida_task_manager/scripts/hri_tasks.py`): Manages the implementation of Human-Robot Interaction (HRI) tasks, including speaking, guest information retrieval, and guest analysis. +* `manipulation_tasks.py` (`ws/src/frida_task_manager/scripts/manipulation_tasks.py`): Manages the implementation of manipulation tasks, including picking, placing, and moving arm joints. +* `nav_tasks.py` (`ws/src/frida_task_manager/scripts/nav_tasks.py`): Manages the implementation of navigation tasks, including moving to specific locations and storing the current location. +* `vision_tasks.py` (`ws/src/frida_task_manager/scripts/vision_tasks.py`): Manages the implementation of vision tasks, including saving face names, checking for persons, and finding free seats. + +## Detailed Example of a Task Flow for `receptionist_task_manager.py` + +Here is a detailed example of a task flow for the `receptionist_task_manager.py` node: + +* The `ReceptionistTaskManager` class is initialized, setting up the ROS node, rate, and subscribers. It also initializes the subtask managers for different areas such as HRI, manipulation, navigation, and vision. +* The `run` method is the main loop for the task manager, which continuously checks the current state and executes the corresponding actions. +* The task flow starts with the `WAITING_GUEST` state, where the robot waits for a guest to be detected. It uses the vision subtask manager to check for a person and follows the detected face using the manipulation subtask manager. +* Once a guest is detected, the state transitions to `SELF_INTRODUCTION`, where the robot introduces itself and asks for the guest's name and favorite drink using the HRI subtask manager. +* The state then transitions to `REQUEST_GUEST_INFORMATION`, where the robot retrieves the guest's information and stores it in the `Guest` class. +* In the `SAVE_USER_FACE` state, the robot saves the guest's face and analyzes it using the vision and HRI subtask managers. +* The robot then navigates to the living room in the `GO_TO_LIVING_ROOM` state using the navigation subtask manager. +* In the `INTRODUCE_GUEST_1` and `INTRODUCE_GUEST_2` states, the robot introduces the guest to the host and other guests using the HRI and manipulation subtask managers. +* The robot then gazes at the current guest in the `GAZE_AT_GUEST` state and informs them about finding a free seat. +* In the `FIND_FREE_SEAT` state, the robot uses the vision subtask manager to find a free seat and directs the guest to it using the manipulation subtask manager. +* The robot waits for the guest to sit in the `WAIT_USER_TO_SIT` state and then transitions to the `GO_TO_ENTRANCE` state to return to the entrance. +* The task flow continues until all guests are processed, and the robot transitions to the `SHUTDOWN` state, indicating the end of the task. + +This detailed example demonstrates how the `receptionist_task_manager.py` node manages the receptionist task by coordinating various subtask managers and transitioning through different states to achieve the desired behavior. The code for this task manager can be found in `ws/src/frida_task_manager/scripts/receptionist_task_manager.py`. The subtask managers for HRI, manipulation, navigation, and vision are implemented in `ws/src/frida_task_manager/scripts/hri_tasks.py`, `ws/src/frida_task_manager/scripts/manipulation_tasks.py`, `ws/src/frida_task_manager/scripts/nav_tasks.py`, and `ws/src/frida_task_manager/scripts/vision_tasks.py` respectively. diff --git a/README.md b/README.md index 130ec34..fa574f3 100644 --- a/README.md +++ b/README.md @@ -107,3 +107,29 @@ rosrun frida_task_manager task_manager_server.py | Franciso Salas | [@Francisco-SP3](http://github.com/Francisco-SP3) | HRI, Navigation | | Leonardo Sánchez | [@LeoLFSH](https://github.com/LeoLFSH) | Mechanics | | Alex Guerrero | [@alex-guerreroc](https://github.com/alex-guerreroc) | Mechanics | + +## Achievements from 2024 +This year, after being accepted to participate in RoboCup 2024 held in Eindhoven, Netherlands, the team focused in developing a robust and reliable set of software modules, tailored to the specific needs for the tasks for the updated rulebook. This approach, had the purpose of showcasing a functional robot for both the Mexican Robotics Tournament (April; Monterrey, Mexico) and the RoboCup (July; Eindhoven, Netherlands). + +The robot was renamed as FRIDA (Friendly Robotic Interactive Domestic Assistant), an acronym reflecting the purporse of the robot, and the name in reference to Mexican culture. + +With the vast knowledge acquired during the international tournament, the team defined the new objectives for the remainder of the year to be: an increased focus in research and literature review, and centralized and offline refactorization of the software and systems. + +## Integration +### Software Architecture +A new empty repository was created, alongside separate repositories for each area, added as submodules of the first. This allowed us to work of different branches of development in the central computational unit (Jetson AGX inside robot). +Every submodule was containerized, using Docker, to ease the installation process and dependency management. +### Task manager +A new package named task_manager was created to handle the flow of each task using general python submodules per area. +There's a Python ROS node for each task, following a state machine architecture. + +## Examples of ROS Nodes Purpose + +* `receptionist_task_manager.py` (`ws/src/frida_task_manager/scripts/receptionist_task_manager.py`): Manages the receptionist task, including guest interaction, face recognition, and navigation to the living room. +* `breakfast_task_manager.py` (`ws/src/frida_task_manager/scripts/breakfast_task_manager.py`): Manages the breakfast task, including picking and placing objects, pouring, and navigating to different locations. +* `demo_tmr24.py` (`ws/src/frida_task_manager/scripts/demo_tmr24.py`): Demonstrates the task manager for the breakfast task, including guest interaction, face recognition, and serving breakfast. +* `task_manager_server.py` (`ws/src/frida_task_manager/scripts/task_manager_server.py`): Serves as a template for developing multiple task managers for various tasks in RoboCup@Home. +* `hri_tasks.py` (`ws/src/frida_task_manager/scripts/hri_tasks.py`): Manages the implementation of Human-Robot Interaction (HRI) tasks, including speaking, guest information retrieval, and guest analysis. +* `manipulation_tasks.py` (`ws/src/frida_task_manager/scripts/manipulation_tasks.py`): Manages the implementation of manipulation tasks, including picking, placing, and moving arm joints. +* `nav_tasks.py` (`ws/src/frida_task_manager/scripts/nav_tasks.py`): Manages the implementation of navigation tasks, including moving to specific locations and storing the current location. +* `vision_tasks.py` (`ws/src/frida_task_manager/scripts/vision_tasks.py`): Manages the implementation of vision tasks, including saving face names, checking for persons, and finding free seats. diff --git a/docker/README.md b/docker/README.md index f153eb6..9e374e0 100644 --- a/docker/README.md +++ b/docker/README.md @@ -48,4 +48,30 @@ xhost + docker exec -it --user $(id -u):$(id -g) container-name bash ``` -**Important:** The `user` parameter is neccessary in order to run docker in rootless mode, otherwise, files and folders created inside the container will be protected and only editable using `sudo`. \ No newline at end of file +**Important:** The `user` parameter is neccessary in order to run docker in rootless mode, otherwise, files and folders created inside the container will be protected and only editable using `sudo`. + +## Examples and Detailed Explanations of ROS Nodes + +### `receptionist_task_manager.py` +The `receptionist_task_manager.py` node manages the receptionist task, including guest interaction, face recognition, and navigation to the living room. It coordinates various subtask managers for HRI, manipulation, navigation, and vision to achieve the desired behavior. + +### `breakfast_task_manager.py` +The `breakfast_task_manager.py` node manages the breakfast task, including picking and placing objects, pouring, and navigating to different locations. It ensures the robot can perform the necessary actions to serve breakfast. + +### `demo_tmr24.py` +The `demo_tmr24.py` node demonstrates the task manager for the breakfast task, including guest interaction, face recognition, and serving breakfast. It showcases the capabilities of the robot in a controlled environment. + +### `task_manager_server.py` +The `task_manager_server.py` node serves as a template for developing multiple task managers for various tasks in RoboCup@Home. It provides a base structure for managing tasks and coordinating subtask managers. + +### `hri_tasks.py` +The `hri_tasks.py` node manages the implementation of Human-Robot Interaction (HRI) tasks, including speaking, guest information retrieval, and guest analysis. It ensures the robot can effectively interact with humans. + +### `manipulation_tasks.py` +The `manipulation_tasks.py` node manages the implementation of manipulation tasks, including picking, placing, and moving arm joints. It ensures the robot can perform the necessary actions to manipulate objects. + +### `nav_tasks.py` +The `nav_tasks.py` node manages the implementation of navigation tasks, including moving to specific locations and storing the current location. It ensures the robot can navigate effectively within its environment. + +### `vision_tasks.py` +The `vision_tasks.py` node manages the implementation of vision tasks, including saving face names, checking for persons, and finding free seats. It ensures the robot can accurately process visual information and interact with its environment. diff --git a/ws/src/frida_task_manager/README.md b/ws/src/frida_task_manager/README.md index 2d06a2d..3cab8cf 100644 --- a/ws/src/frida_task_manager/README.md +++ b/ws/src/frida_task_manager/README.md @@ -24,4 +24,34 @@ The launch file `receptionist.launch` executes the nodes needed: `arm_joint_server`: For moving the arm to predefined locations or following a face. ### Navigation -Nodes neccesary for navigation between rooms. \ No newline at end of file +Nodes neccesary for navigation between rooms. + +## Examples of ROS Nodes Purpose + +* `receptionist_task_manager.py` (`ws/src/frida_task_manager/scripts/receptionist_task_manager.py`): Manages the receptionist task, including guest interaction, face recognition, and navigation to the living room. +* `breakfast_task_manager.py` (`ws/src/frida_task_manager/scripts/breakfast_task_manager.py`): Manages the breakfast task, including picking and placing objects, pouring, and navigating to different locations. +* `demo_tmr24.py` (`ws/src/frida_task_manager/scripts/demo_tmr24.py`): Demonstrates the task manager for the breakfast task, including guest interaction, face recognition, and serving breakfast. +* `task_manager_server.py` (`ws/src/frida_task_manager/scripts/task_manager_server.py`): Serves as a template for developing multiple task managers for various tasks in RoboCup@Home. +* `hri_tasks.py` (`ws/src/frida_task_manager/scripts/hri_tasks.py`): Manages the implementation of Human-Robot Interaction (HRI) tasks, including speaking, guest information retrieval, and guest analysis. +* `manipulation_tasks.py` (`ws/src/frida_task_manager/scripts/manipulation_tasks.py`): Manages the implementation of manipulation tasks, including picking, placing, and moving arm joints. +* `nav_tasks.py` (`ws/src/frida_task_manager/scripts/nav_tasks.py`): Manages the implementation of navigation tasks, including moving to specific locations and storing the current location. +* `vision_tasks.py` (`ws/src/frida_task_manager/scripts/vision_tasks.py`): Manages the implementation of vision tasks, including saving face names, checking for persons, and finding free seats. + +## Detailed Example of a Task Flow for `receptionist_task_manager.py` + +Here is a detailed example of a task flow for the `receptionist_task_manager.py` node: + +* The `ReceptionistTaskManager` class is initialized, setting up the ROS node, rate, and subscribers. It also initializes the subtask managers for different areas such as HRI, manipulation, navigation, and vision. +* The `run` method is the main loop for the task manager, which continuously checks the current state and executes the corresponding actions. +* The task flow starts with the `WAITING_GUEST` state, where the robot waits for a guest to be detected. It uses the vision subtask manager to check for a person and follows the detected face using the manipulation subtask manager. +* Once a guest is detected, the state transitions to `SELF_INTRODUCTION`, where the robot introduces itself and asks for the guest's name and favorite drink using the HRI subtask manager. +* The state then transitions to `REQUEST_GUEST_INFORMATION`, where the robot retrieves the guest's information and stores it in the `Guest` class. +* In the `SAVE_USER_FACE` state, the robot saves the guest's face and analyzes it using the vision and HRI subtask managers. +* The robot then navigates to the living room in the `GO_TO_LIVING_ROOM` state using the navigation subtask manager. +* In the `INTRODUCE_GUEST_1` and `INTRODUCE_GUEST_2` states, the robot introduces the guest to the host and other guests using the HRI and manipulation subtask managers. +* The robot then gazes at the current guest in the `GAZE_AT_GUEST` state and informs them about finding a free seat. +* In the `FIND_FREE_SEAT` state, the robot uses the vision subtask manager to find a free seat and directs the guest to it using the manipulation subtask manager. +* The robot waits for the guest to sit in the `WAIT_USER_TO_SIT` state and then transitions to the `GO_TO_ENTRANCE` state to return to the entrance. +* The task flow continues until all guests are processed, and the robot transitions to the `SHUTDOWN` state, indicating the end of the task. + +This detailed example demonstrates how the `receptionist_task_manager.py` node manages the receptionist task by coordinating various subtask managers and transitioning through different states to achieve the desired behavior. The code for this task manager can be found in `ws/src/frida_task_manager/scripts/receptionist_task_manager.py`. The subtask managers for HRI, manipulation, navigation, and vision are implemented in `ws/src/frida_task_manager/scripts/hri_tasks.py`, `ws/src/frida_task_manager/scripts/manipulation_tasks.py`, `ws/src/frida_task_manager/scripts/nav_tasks.py`, and `ws/src/frida_task_manager/scripts/vision_tasks.py` respectively.