diff --git a/README.md b/README.md index 638c548..7ea261c 100644 --- a/README.md +++ b/README.md @@ -1,130 +1,173 @@ -# Robotics Application Manager (RAM) Documentation +# 🤖 Robotics Application Manager -## Table of Contents +The **🤖 Robotics Application Manager** (RAM) provides an advanced framework for integrating, configuring, and managing robotics workflows. Designed as a dynamic state machine, it facilitates smooth transitions across different application states. As part of the [🌐 JdeRobot](https://jderobot.github.io/) ecosystem, RAM caters to a wide array of robotics and computer vision applications. -1. [Project Overview](#project-overview) -2. [Main Class: `Manager`](#main-class-manager) - - [Purpose and Functionality](#purpose-and-functionality) - - [States and Transitions](#states-and-transitions) - - [Key Methods](#key-methods) - - [Interactions with Other Components](#interactions-with-other-components) -3. [Usage Examples](#usage-examples) +--- -## Project Overview +## 🌟 Highlights -The Robotics Application Manager (RAM) is an advanced manager for executing robotic applications. It operates as a state machine, managing the lifecycle of robotic applications from initialization to termination. +- **🔧 Modular Framework:** Simplifies management of diverse robotics tasks. +- **💻 Multi-Platform Support:** Ensures compatibility across operating systems. +- **😊 User-Friendly:** Built for developers and researchers. +- **📈 Scalable Design:** Adapts seamlessly to projects of any size. +- **🧠 Intelligent State Management:** Automates application state transitions. -## Main Class: `Manager` +--- -### Purpose and Functionality +## 🛠️ Getting Started -The `Manager` class is the core of RAM, orchestrating operations and managing transitions between various application states. +### 1. Clone the Repository -### States and Transitions +```bash +git clone https://github.com/JdeRobot/RoboticsApplicationManager.git +cd RoboticsApplicationManager +``` -- **States**: - - `idle`: The initial state, waiting for a connection. - - `connected`: Connected and ready to initiate processes. - - `world_ready`: The world environment is set up and ready. - - `visualization_ready`: Visualization tools are prepared and ready. - - `application_running`: A robotic application is actively running. - - `paused`: The application is paused. -- **Transitions**: - - `connect`: Moves from `idle` to `connected`. - - `launch_world`: Initiates the world setup from `connected`. - - `prepare_visualization`: Prepares the visualization tools in `world_ready`. - - `run_application`: Starts the application in `visualization_ready` or `paused`. - - `pause`: Pauses the running application. - - `resume`: Resumes a paused application. - - `terminate`: Stops the application and goes back to `visualization_ready`. - - `stop`: Completely stops the application. - - `disconnect`: Disconnects from the current session and returns to `idle`. +### 2. Install Dependencies -### Key Methods +```bash +pip install -r docs/requirements.txt +``` -- `on_connect(self, event)`: Manages the transition to the 'connected' state. -- `on_launch_world(self, event)`: Prepares and launches the robotic world. -- `on_prepare_visualization(self, event)`: Sets up visualization tools. -- `on_run_application(self, event)`: Executes the robotic application. -- `on_pause(self, msg)`: Pauses the running application. -- `on_resume(self, msg)`: Resumes the paused application. -- `on_terminate(self, event)`: Terminates the running application. -- `on_disconnect(self, event)`: Handles disconnection and cleanup. -- **Exception Handling**: Details how specific errors are managed in each method. +--- -### Interactions with Other Components +## 🚀 Developing a New RAM Launcher -#### Interaction Between `Manager` and `ManagerConsumer` +### Steps to Build a Launcher -1. **Message Queue Integration**: `ManagerConsumer` puts received messages into `manager_queue` for `Manager` to process. -2. **State Updates and Commands**: `Manager` sends state updates or commands to the client through `ManagerConsumer`. -3. **Client Connection Handling**: `Manager` relies on `ManagerConsumer` for client connection and disconnection handling. -4. **Error Handling**: `ManagerConsumer` communicates exceptions back to the client and `Manager`. -5. **Lifecycle Management**: `Manager` controls the start and stop of the `ManagerConsumer` WebSocket server. +1. **Configure Transitions**: + - Add entries in `launcher_visualization.py` for visualization setups or `launcher_world.py` for world configurations. -#### Interaction Between `Manager` and `LauncherWorld` +2. **Create Required Modules**: + - Implement custom modules like `launcher_abc_module.py`. -1. **World Initialization and Launching**: `Manager` initializes `LauncherWorld` with specific configurations, such as world type (e.g., `gazebo`, `drones`) and the launch file path. -2. **Dynamic Module Management**: `LauncherWorld` dynamically launches modules based on the world configuration and ROS version, as dictated by `Manager`. -3. **State Management and Transition**: The state of `Manager` is updated in response to the actions performed by `LauncherWorld`. For example, once the world is ready, `Manager` may transition to the `world_ready` state. -4. **Termination and Cleanup**: `Manager` can instruct `LauncherWorld` to terminate the world environment through its `terminate` method. `LauncherWorld` ensures a clean and orderly shutdown of all modules and resources involved in the world setup. -5. **Error Handling and Logging**: `Manager` handles exceptions and errors that may arise during the world setup or termination processes, ensuring robust operation. +3. **Activate the Setup**: + - Utilize classes such as `LauncherVisualization` to execute the new configuration. -#### Interaction Between `Manager` and `LauncherVisualization` +--- -1. **Visualization Setup**: `Manager` initializes `LauncherVisualization` with a specific visualization configuration, which can include types like `console`, `gazebo_gra`, `gazebo_rae`, etc. -2. **Module Launching for Visualization**: `LauncherVisualization` dynamically launches visualization modules based on the configuration provided by `Manager`. -3. **State Management and Synchronization**: Upon successful setup of the visualization tools, `Manager` can update its state (e.g., to `visualization_ready`) to reflect the readiness of the visualization environment. -4. **Termination of Visualization Tools**: `Manager` can instruct `LauncherVisualization` to terminate the current visualization setup using its `terminate` method. -5. **Error Handling and Logging**: `Manager` is equipped to manage exceptions and errors that might occur during the setup or termination of visualization tools. +## 🤖 Utilizing the Dummy RAM Client -#### Interaction Between `Manager` and `application_process` +The Dummy RAM Client streamlines testing and debugging by simulating key application transitions. -1. **Application Execution**: `Manager` initiates the `application_process` when transitioning to the `application_running` state. -2. **Application Configuration and Launching**: Before launching the `application_process`, `Manager` configures the necessary parameters. -3. **Process Management**: `Manager` monitors and controls the `application_process`. -4. **Error Handling and Logging**: `Manager` is responsible for handling any errors or exceptions that occur during the execution of the `application_process`. -5. **State Synchronization**: The state of the `application_process` is closely synchronized with the state machine in `Manager`. +### Usage Instructions -#### Interaction Between `Manager` and `Server` (Specific to RoboticsAcademy Applications) +1. **Clone the Repository**: -1. **Dedicated WebSocket Server for GUI Updates**: `Server` is used exclusively for RoboticsAcademy applications that require real-time interaction with a web-based GUI. -2. **Client Communication for GUI Module**: For RoboticsAcademy applications with a GUI module, `Server` handles incoming and outgoing messages. -3. **Real-time Interaction and Feedback**: `Server` allows for real-time feedback and interaction within the browser-based GUI. -4. **Conditional Operation Based on Application Type**: `Manager` initializes and controls `Server` based on the specific needs of the RoboticsAcademy application being executed. -5. **Error Handling and Logging**: `Manager` ensures robust error handling for `Server`. + ```bash + git clone https://github.com/JdeRobot/RoboticsApplicationManager.git -b + ``` -## Usage Example +2. **Run a Docker Container**: -1. **Connecting to RAM**: + ```bash + docker run --rm -it -p 7164:7164 -p 6080:6080 -p 1108:1108 -p 7163:7163 jderobot/robotics-backend + ``` - - Initially, the RAM is in the `idle` state. - - A client (e.g., a user interface or another system) connects to RAM, triggering the `connect` transition and moving RAM to the `connected` state. +3. **Execute the Dummy Client**: -2. **Launching the World**: + ```bash + cd RoboticsApplicationManager/test/ + python3 dummyclient.py + ``` - - Once connected, the client can request RAM to launch a robotic world by sending a `launch_world` command. - - RAM transitions to the `world_ready` state after successfully setting up the world environment. + Access the simulation at [http://127.0.0.1:6080/vnc.html](http://127.0.0.1:6080/vnc.html). -3. **Setting Up Visualization**: +--- - - After the world is ready, the client requests RAM to prepare the visualization tools with a `prepare_visualization` command. - - RAM transitions to the `visualization_ready` state, indicating that visualization tools are set up and ready. +## 🔑 Core Functionalities -4. **Running an Application**: +### Manager Class Highlights - - The client then requests RAM to run a specific robotic application, moving RAM into the `application_running` state. - - The application executes, and RAM handles its process management, including monitoring and error handling. +- **Primary States**: + - `idle`: Waiting for connection. + - `connected`: Ready for communication. + - `world_ready`: Environment configured. + - `visualization_ready`: Visualization initialized. + - `application_running`: Application active. + - `paused`: Application paused. -5. **Pausing and Resuming Application**: +- **State Transitions**: + - Include `connect`, `launch_world`, `prepare_visualization`, `run_application`, `pause`, `resume`, `terminate`, `stop`, and `disconnect`. - - The client can send `pause` and `resume` commands to RAM to control the application's execution. - - RAM transitions to the `paused` state when paused and returns to `application_running` upon resumption. +### Key System Components -6. **Stopping the Application**: +- **ManagerConsumer**: Oversees client communication and message queues. +- **LauncherWorld**: Dynamically sets up robotic environments. +- **LauncherVisualization**: Initializes visualization modules. +- **Application Process**: Manages execution flow. +- **Server Integration**: Enables live GUI-based controls. - - Finally, the client can send a `stop` command to halt the application. - - RAM stops the application and transitions back to the `visualization_ready` state, ready for new commands. +### Essential Methods + +- `on_connect`: Moves to `connected` state. +- `on_launch_world`: Sets up the robotic environment. +- `on_prepare_visualization`: Configures visualization tools. +- `on_run_application`: Starts the application. +- `on_pause` / `on_resume`: Manages pausing and resuming. +- `on_terminate`: Ends application operations. +- `on_disconnect`: Handles cleanup and disconnection tasks. + +--- + +## 👥 Contributors + +Special thanks to all contributors: + +- ango1994 +- ReyDoran +- javizqh +- dduro2020 +- pawanw17 +- OscarMrZ +- Blancasr +- Arcane-01 +- espilya +- pariaspe +- dpascualhe +- jmplaza +- CDAM2020 + +--- + +## 🤝 Contributing to RAM + +Want to contribute? Here's how: + +1. **Fork the Repository**: + + ```bash + git checkout -b feature/your-feature + ``` + +2. **Commit Your Changes**: + + ```bash + git commit -m "✨ Add feature description" + ``` + +3. **Push to Your Branch**: + + ```bash + git push origin feature/your-feature + ``` + +4. **Submit a Pull Request**: + - Open a PR for review and integration. + +--- + +## 📜 License + +This project is licensed under the [📜 GPL v3 License](LICENSE). + +--- + +## 📬 Get in Touch + +Have questions or feedback? Contact us via the [🌐 JdeRobot Team](https://jderobot.github.io/) or submit issues directly on the repository. + +--- + +Thank you for choosing RAM! 🚀 Happy Building! 💻 -7. **Disconnecting**: - - Once all tasks are completed, the client can disconnect from RAM, which then returns to the `idle` state, ready for a new session.