Skip to content

Updated README with improved structure and content #181

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: humble-devel
Choose a base branch
from
Open

Updated README with improved structure and content #181

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
64e938d
Updated README with improved structure and content
Uni-Creator Dec 29, 2024
4f3b846
Update README.md
Uni-Creator Dec 29, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
231 changes: 137 additions & 94 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <src-branch>
```

## 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.