diff --git a/README.MD b/README.MD index 21e192c..2b02fe7 100644 --- a/README.MD +++ b/README.MD @@ -14,8 +14,7 @@ The site hosts technical documentation for Ubiquity Robotics robots, covering ha The documentation is built and deployed automatically using GitHub Actions. The latest version is available at: - -**[https://paveljolak.github.io/learn2/](https://paveljolak.github.io/learn2/)** +**[https://learn2.ubiquityrobotics.com/jazzy/](https://learn2.ubiquityrobotics.com/jazzy/)** ## Local Development @@ -23,7 +22,7 @@ To build and run the documentation locally: ```bash -git clone https://github.com/Paveljolak/learn2.git +git clone https://github.com/UbiquityRobotics/learn2.git cd learn2 git fetch --all git branch -a diff --git a/docs/_static/odin_fleet/config_page.png b/docs/_static/odin_fleet/config_page.png new file mode 100644 index 0000000..827e696 Binary files /dev/null and b/docs/_static/odin_fleet/config_page.png differ diff --git a/docs/_static/odin_fleet/dashboard_page.png b/docs/_static/odin_fleet/dashboard_page.png new file mode 100644 index 0000000..0310899 Binary files /dev/null and b/docs/_static/odin_fleet/dashboard_page.png differ diff --git a/docs/_static/odin_fleet/deleting_queued_tasks.png b/docs/_static/odin_fleet/deleting_queued_tasks.png new file mode 100644 index 0000000..b5af152 Binary files /dev/null and b/docs/_static/odin_fleet/deleting_queued_tasks.png differ diff --git a/docs/_static/odin_fleet/diagnostics_page.png b/docs/_static/odin_fleet/diagnostics_page.png new file mode 100644 index 0000000..73ecce6 Binary files /dev/null and b/docs/_static/odin_fleet/diagnostics_page.png differ diff --git a/docs/_static/odin_fleet/dispatching_task.png b/docs/_static/odin_fleet/dispatching_task.png new file mode 100644 index 0000000..c02b5f8 Binary files /dev/null and b/docs/_static/odin_fleet/dispatching_task.png differ diff --git a/docs/_static/odin_fleet/feedback_page.png b/docs/_static/odin_fleet/feedback_page.png new file mode 100644 index 0000000..64b08e0 Binary files /dev/null and b/docs/_static/odin_fleet/feedback_page.png differ diff --git a/docs/_static/odin_fleet/map_visualization.png b/docs/_static/odin_fleet/map_visualization.png new file mode 100644 index 0000000..0e520b9 Binary files /dev/null and b/docs/_static/odin_fleet/map_visualization.png differ diff --git a/docs/_static/odin_fleet/map_visualization_robot_in_transit.png b/docs/_static/odin_fleet/map_visualization_robot_in_transit.png new file mode 100644 index 0000000..18d0b2b Binary files /dev/null and b/docs/_static/odin_fleet/map_visualization_robot_in_transit.png differ diff --git a/docs/_static/odin_fleet/robot_card_idle.png b/docs/_static/odin_fleet/robot_card_idle.png new file mode 100644 index 0000000..59d5ffe Binary files /dev/null and b/docs/_static/odin_fleet/robot_card_idle.png differ diff --git a/docs/_static/odin_fleet/robot_card_in_transit.png b/docs/_static/odin_fleet/robot_card_in_transit.png new file mode 100644 index 0000000..76afefb Binary files /dev/null and b/docs/_static/odin_fleet/robot_card_in_transit.png differ diff --git a/docs/_static/odin_fleet/robot_decomission.png b/docs/_static/odin_fleet/robot_decomission.png new file mode 100644 index 0000000..8f5ac98 Binary files /dev/null and b/docs/_static/odin_fleet/robot_decomission.png differ diff --git a/docs/_static/odin_fleet/robots_list.png b/docs/_static/odin_fleet/robots_list.png new file mode 100644 index 0000000..15a47c8 Binary files /dev/null and b/docs/_static/odin_fleet/robots_list.png differ diff --git a/docs/_static/odin_fleet/task_cancelation.png b/docs/_static/odin_fleet/task_cancelation.png new file mode 100644 index 0000000..9a0c90b Binary files /dev/null and b/docs/_static/odin_fleet/task_cancelation.png differ diff --git a/docs/_static/odin_fleet/task_delivery.png b/docs/_static/odin_fleet/task_delivery.png new file mode 100644 index 0000000..eeea669 Binary files /dev/null and b/docs/_static/odin_fleet/task_delivery.png differ diff --git a/docs/_static/odin_fleet/task_dispatched.png b/docs/_static/odin_fleet/task_dispatched.png new file mode 100644 index 0000000..b92dadc Binary files /dev/null and b/docs/_static/odin_fleet/task_dispatched.png differ diff --git a/docs/_static/odin_fleet/task_gotoplace.png b/docs/_static/odin_fleet/task_gotoplace.png new file mode 100644 index 0000000..6aefdb9 Binary files /dev/null and b/docs/_static/odin_fleet/task_gotoplace.png differ diff --git a/docs/_static/odin_fleet/task_patrol.png b/docs/_static/odin_fleet/task_patrol.png new file mode 100644 index 0000000..a8c564d Binary files /dev/null and b/docs/_static/odin_fleet/task_patrol.png differ diff --git a/docs/_static/odin_fleet/task_queue_bin.png b/docs/_static/odin_fleet/task_queue_bin.png new file mode 100644 index 0000000..3e0bc60 Binary files /dev/null and b/docs/_static/odin_fleet/task_queue_bin.png differ diff --git a/docs/_static/odin_fleet/tasks_list.png b/docs/_static/odin_fleet/tasks_list.png new file mode 100644 index 0000000..4418f81 Binary files /dev/null and b/docs/_static/odin_fleet/tasks_list.png differ diff --git a/docs/_static/odin_fleet/tasks_queue.png b/docs/_static/odin_fleet/tasks_queue.png new file mode 100644 index 0000000..eb4041a Binary files /dev/null and b/docs/_static/odin_fleet/tasks_queue.png differ diff --git a/docs/_static/shutdown/shutdown_GUI.png b/docs/_static/shutdown/shutdown_GUI.png new file mode 100644 index 0000000..0ace972 Binary files /dev/null and b/docs/_static/shutdown/shutdown_GUI.png differ diff --git a/docs/_static/shutdown/turnedOffRaspberry.jpg b/docs/_static/shutdown/turnedOffRaspberry.jpg new file mode 100644 index 0000000..2ec45b0 Binary files /dev/null and b/docs/_static/shutdown/turnedOffRaspberry.jpg differ diff --git a/docs/_static/unboxing/Automotive_fuse_battery_diagram.jpg b/docs/_static/unboxing/Automotive_fuse_battery_diagram.jpg new file mode 100644 index 0000000..d3df60e Binary files /dev/null and b/docs/_static/unboxing/Automotive_fuse_battery_diagram.jpg differ diff --git a/docs/_static/unboxing/batt_to_batt_series_connction_wires.jpg b/docs/_static/unboxing/batt_to_batt_series_connction_wires.jpg new file mode 100644 index 0000000..7869026 Binary files /dev/null and b/docs/_static/unboxing/batt_to_batt_series_connction_wires.jpg differ diff --git a/docs/_static/unboxing/batt_to_batt_series_connection.jpg b/docs/_static/unboxing/batt_to_batt_series_connection.jpg new file mode 100644 index 0000000..f5f50c2 Binary files /dev/null and b/docs/_static/unboxing/batt_to_batt_series_connection.jpg differ diff --git a/docs/_static/unboxing/batteries_sitting_in_the_battery_bay.jpg b/docs/_static/unboxing/batteries_sitting_in_the_battery_bay.jpg new file mode 100644 index 0000000..e95b8f2 Binary files /dev/null and b/docs/_static/unboxing/batteries_sitting_in_the_battery_bay.jpg differ diff --git a/docs/_static/unboxing/battery_bay_brackets.jpg b/docs/_static/unboxing/battery_bay_brackets.jpg new file mode 100644 index 0000000..7bc28f4 Binary files /dev/null and b/docs/_static/unboxing/battery_bay_brackets.jpg differ diff --git a/docs/_static/unboxing/battery_type.jpg b/docs/_static/unboxing/battery_type.jpg new file mode 100644 index 0000000..eda4344 Binary files /dev/null and b/docs/_static/unboxing/battery_type.jpg differ diff --git a/docs/_static/unboxing/connecting_the_batterie_in_series.jpg b/docs/_static/unboxing/connecting_the_batterie_in_series.jpg new file mode 100644 index 0000000..f29b42d Binary files /dev/null and b/docs/_static/unboxing/connecting_the_batterie_in_series.jpg differ diff --git a/docs/_static/unboxing/connecting_the_batteries_in_series2.jpg b/docs/_static/unboxing/connecting_the_batteries_in_series2.jpg new file mode 100644 index 0000000..c38d431 Binary files /dev/null and b/docs/_static/unboxing/connecting_the_batteries_in_series2.jpg differ diff --git a/docs/_static/unboxing/one_battery_sitting_in_the_battery_bay.jpg b/docs/_static/unboxing/one_battery_sitting_in_the_battery_bay.jpg new file mode 100644 index 0000000..3a18122 Binary files /dev/null and b/docs/_static/unboxing/one_battery_sitting_in_the_battery_bay.jpg differ diff --git a/docs/_static/unboxing/snapshot_1773415303723.jpg b/docs/_static/unboxing/snapshot_1773415303723.jpg new file mode 100644 index 0000000..0be8f5e Binary files /dev/null and b/docs/_static/unboxing/snapshot_1773415303723.jpg differ diff --git a/docs/_static/unboxing/snapshot_1774619884018.jpg b/docs/_static/unboxing/snapshot_1774619884018.jpg new file mode 100644 index 0000000..aebf49c Binary files /dev/null and b/docs/_static/unboxing/snapshot_1774619884018.jpg differ diff --git a/docs/conf.py b/docs/conf.py index b4b0bce..7b40a69 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -21,6 +21,7 @@ # -- General configuration --------------------------------------------------- extensions = [ 'sphinx_rtd_theme', + 'sphinx_design', 'sphinx.ext.viewcode', 'sphinx.ext.githubpages', ] @@ -84,8 +85,13 @@ # project_name = project.replace(' ', '_') +# IMPORTANT: +# --------------------------------------------------------------------------------------------- +# This part gives error that language does not exists and set it to "None" in the local build process +# DO NOT CHANGE IT: you will break the version management for the deployed documentation html_context['current_language'] = '' html_context['language'] = '' +# --------------------------------------------------------------------------------------------- # -- "Edit on GitHub" links -------------------------------------------------- html_context['display_github'] = True diff --git a/docs/conf.py.orig b/docs/conf.py.orig index 1b821b5..b4b0bce 100644 --- a/docs/conf.py.orig +++ b/docs/conf.py.orig @@ -14,7 +14,7 @@ sys.path.insert(0, os.path.abspath('../src')) # -- Project information ----------------------------------------------------- project = 'Ubiquity Robotics Documentation' copyright = '2025, Ubiquity Robotics' -author = 'Pavel for now' +author = 'Paveljolak' version = '' release = '1.0.0' @@ -36,6 +36,14 @@ pygments_style = None html_theme = 'sphinx_rtd_theme' html_static_path = ['_static'] +html_logo = "_static/logos/UbiquityRobotics_Logo_Full_White.png" + +html_css_files = [ + 'custom.css' +] + +html_js_files = ['custom.js'] + # -- RTD lower-left menu setup ----------------------------------------------- try: html_context @@ -45,7 +53,8 @@ except NameError: html_context['display_lower_left'] = True # Repo and environment info -REPO_NAME = os.environ.get('REPO_NAME', '') +full_repo = os.environ.get('GITHUB_REPOSITORY', '') +REPO_NAME = full_repo.split('/')[-1] OWNER = os.environ.get('OWNER', '') # Use ALL_VERSIONS from workflow environment @@ -56,10 +65,19 @@ current_version = os.environ.get('CURRENT_BRANCH') or (ALL_VERSIONS[0] if ALL_VE html_context['current_version'] = current_version html_context['version'] = current_version + # Base URL for GitHub Pages -GITHUB_PAGES_BASE = f"https://{OWNER}.github.io/{REPO_NAME}" -# Set versions for selector with absolute URLs +# Get the custom domain +CUSTOM_DOMAIN = os.environ.get("CUSTOM_DOMAIN", "") + +# If the DOMAIN exists in the workflow then use it +if CUSTOM_DOMAIN: + GITHUB_PAGES_BASE = f"https://{REPO_NAME}.{CUSTOM_DOMAIN}" +else: + GITHUB_PAGES_BASE = f"https://{OWNER}.github.io/{REPO_NAME}"# Set versions for selector with absolute URLs + +# Build the absolute URLs for each version html_context['versions'] = [ (v, f"{GITHUB_PAGES_BASE}/{v}/") for v in ALL_VERSIONS ] @@ -71,8 +89,7 @@ html_context['language'] = '' # -- "Edit on GitHub" links -------------------------------------------------- html_context['display_github'] = True -html_context['github_user'] = '' +html_context['github_user'] = OWNER html_context['github_repo'] = REPO_NAME html_context['github_version'] = f'{current_version}/docs/' - diff --git a/docs/driving/connecting.rst b/docs/driving/connecting.rst index 158e912..f5dd765 100644 --- a/docs/driving/connecting.rst +++ b/docs/driving/connecting.rst @@ -135,6 +135,15 @@ Example: | +.. tip:: + + If the robot cannot find your local network, first list nearby Wi-Fi networks from the robot: + + .. code-block:: bash + + nmcli device wifi list + + If your local Wi-Fi (SSID) does not appear in the list, restart the robot and try the connection process again. .. .. important:: diff --git a/docs/driving/shutdown.rst b/docs/driving/shutdown.rst new file mode 100644 index 0000000..e0eac4b --- /dev/null +++ b/docs/driving/shutdown.rst @@ -0,0 +1,44 @@ +Shutting Down the Robot +======================= + +Step 1: Choose Robot Shutdown Method +#################################### + +You can shut down the robot either from the GUI or from a terminal session connected to the robot. + +Method 1: Shutdown from GUI +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. image:: /_static/shutdown/shutdown_GUI.png + :alt: Shutdown from GUI + :width: 600px + :align: center + +| + +Method 2: Shutdown from Terminal +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Open a terminal session connected to the robot (see :doc:`./connecting` for details) and run: + +.. code-block:: bash + + sudo shutdown -h now + +Step 2: Wait for Shutdown Complete +################################## + +After issuing the shutdown command or selecting the shutdown option from the GUI, wait until the Raspberry Pi LED turns red. +This indicates the system has fully shut down and all data has been safely written. + +.. image:: /_static/shutdown/turnedOffRaspberry.jpg + :alt: Raspberry Pi LED turned red (shutdown complete) + :width: 600px + :align: center + +| + +Step 3: Power Off the Robot +########################### + +Once the Raspberry Pi LED is red, turn the robot off using the on/off switch. \ No newline at end of file diff --git a/docs/ez_map/ez_map_guide.rst b/docs/ez_map/ez_map_guide.rst index fd43681..d072c68 100644 --- a/docs/ez_map/ez_map_guide.rst +++ b/docs/ez_map/ez_map_guide.rst @@ -62,10 +62,25 @@ The EZ-Map interface is available on the following webpage: http://:3000 +Alternatively, you can use the robot's hostname (where ``XXXX`` is your robot's unique ID): + +.. code-block:: bash + + http://ubiquityrobotXXXX.local:3000 + .. note:: This ``ROBOT-IP`` is the same IP that you used to connect to the robot. If you followed the :doc:`../driving/connecting` properly then you should have this IP. + The hostname method may or may not work depending on your network's DNS or mDNS configuration. + + +.. danger:: + + **CHECK YOUR BROWSER ADDRESS BAR!** + + Modern browsers (like Chrome or Safari) often automatically force an ``https://`` connection. + EZ-Map **requires** ``http://`` to function. If the page does not load, or you see a "Connection Refused" error, manually change the ``https://`` back to ``http://`` in your address bar. .. warning:: diff --git a/docs/index.rst b/docs/index.rst index 40295ea..b618240 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -34,7 +34,7 @@ Sections | -- `Driving the Robot `_: Learn how to operate your robot in the most basic way possible. How to drive it through Teleop and through our custom sofware EZ-Map. +- `Driving the Robot `_: Learn how to operate your robot in the most basic way possible. How to drive it through Teleop and through our custom sofware EZ-Map. This section also includes advanced motor parameter configuration. | @@ -42,7 +42,11 @@ Sections | -- `Troubleshooting `_: Solutions to common hardware and software issues. Your first stop if you encounter problems. +- `OdinFleet `_: Our custom OdinFleet software for managing fleets through a web dashboard, build on top of Open-RMF. + +| + +- `Let's get technical `_: Solutions to common hardware and software issues. Your first stop if you encounter problems. ---- @@ -85,6 +89,7 @@ Sections driving/connecting driving/teleop driving/ez_map_simple_drive + driving/shutdown .. _ez_map: @@ -96,14 +101,32 @@ Sections ez_map/ez_map_intro ez_map/ez_map_guide + +.. _odin_fleet: + +.. toctree:: + :maxdepth: 2 + :caption: OdinFleet + + odin_fleet/odin_fleet_intro + odin_fleet/odin_fleet_guide + + .. _troubleshooting: .. toctree:: :maxdepth: 2 - :caption: Troubleshooting + :caption: Let's get Technical troubleshooting/hardware/lidars troubleshooting/hardware/rpi troubleshooting/hardware/pi_camera + troubleshooting/hardware/motor_parameters + +.. _troubleshooting_tips: +.. toctree:: + :maxdepth: 2 + :caption: Troubleshooting + troubleshooting/troubleshooting_tips diff --git a/docs/odin_fleet/odin_fleet_guide.rst b/docs/odin_fleet/odin_fleet_guide.rst new file mode 100644 index 0000000..58ec334 --- /dev/null +++ b/docs/odin_fleet/odin_fleet_guide.rst @@ -0,0 +1,322 @@ +OdinFleet Guide +=============== + +This section provides a detailed guide to OdinFleet, starting with core concepts and then covering the Web Dashboard features in more detail. + +---- + +Core Concepts +############# + +Fleet +----- + +A fleet is a group of robots that share common capabilities and are managed through a single fleet adapter. + +Task +---- + +A task is a unit of work assigned to a robot, such as navigation, delivery, or patrol. + +Traffic Scheduling +------------------ + +Traffic scheduling ensures that robots move through shared spaces without collisions or deadlocks. + +OdinFleet coordinates robot paths using time-based schedules rather than direct robot-to-robot communication. + +Shared Resources +---------------- + +Shared resources such as doors, lifts, and narrow corridors are centrally menaged to prevent conflicts between robots from the same and different fleets. + +---- + +Core OdinFleet Features +####################### + +This section describes the main features of OdinFleet. + +.. image:: /_static/odin_fleet/dashboard_page.png + :alt: Dashboard Page + :width: 800px + :align: center + +OdinFleet currently supports the following core functionalities: + +- **Go to Place** - Sends a robot or an entire fleet to a specified location on the map. +- **Patrol** - Commands a robot or fleet to continuously move between defined waypoints. +- **Delivery** - Directs a robot to pick up an item from a specified location and deliver it to a designated drop-off point. + +Go to Place +----------- + +The **Go To Place** command allows users to send a robot or fleet to a selected destination on the map. + +You add a Go to Place task by selecting the robot or a fleet you want to use and then setting the location you want the fleet or the robot to move to. + +.. image of move to task + +.. image:: /_static/odin_fleet/task_gotoplace.png + :alt: Task - Go to Place + :width: 800px + :align: center + +| + +Patrol +------ + +The **Patrol** command enables robots to continuously move between predefined waypoints. +This is useful for monitoring areas or performing repetitive tasks. + +To create a Patrol task, select a robot or fleet and define at least two waypoints. +A minimum of two locations is required, selecting only one location will be treated as a **Go To Place** task. + +.. image:: /_static/odin_fleet/task_patrol.png + :alt: Task - Patrol + :width: 800px + :align: center + +| + +Delivery +-------- + +The **Delivery** command allows a robot to move to a specified pickup location, collect an an item using its ID, and deliver it to a specified drop-off point. +This feature is designed for efficient transport between predefined location. + +To create a Delivery task, select the robot or fleet, define the pickup and drop-off locations, and provide the ID of the cargo. + +.. image:: /_static/odin_fleet/task_delivery.png + :alt: Task - Delivery + :width: 800px + :align: center + +| + +Task Queue +########## + +All created tasks are added to the Task Queue. + +.. image:: /_static/odin_fleet/tasks_queue.png + :alt: Tasks Queue + :width: 400px + :align: center + +To execute a task, select it from the queue and confirm dispatch. +A prompt will display the task name and description for verification before execution. +Once confirmed, the assigned robot or fleet will begin the task. + +.. raw:: html + +
+
+ Tasks Queue - Dispatching task. + Tasks Queue - Task dispatched. +
+
+ +After a task is completed, it can be re-dispatched by selecting it again from the queue. + +.. image:: /_static/odin_fleet/task_dispatched.png + :alt: Tasks Queue - Dispatched task + :width: 300px + :align: center + +Tasks can be removed by clicking the bin icon. +A confirmation prompt ensures tasks are not deleted accidentally. +One confirmed, the task is permanently removed. + +.. image:: /_static/odin_fleet/task_queue_bin.png + :alt: Tasks Queue - Remove queue bin icon + :width: 800px + :align: center + +.. image:: /_static/odin_fleet/deleting_queued_tasks.png + :alt: Tasks Queue - Deleting a task + :width: 800px + :align: center + +| + +Task List +######### + +The Task List page displays all tasks that have been dispatched. + +For each task, you can view its type, dispatch date and time, duration, and current status (queued, in progress, completed, or cancelled). + +.. image:: /_static/odin_fleet/tasks_list.png + :alt: Tasks List + :width: 800px + :align: center + +Clicking on a task will give you a prompt with the choice of cancelling the task or keeping it alive. + +.. image:: /_static/odin_fleet/task_cancelation.png + :alt: Tasks List - Cancelling a task + :width: 800px + :align: center + +| + +.. note:: + + Only dispatched tasks appear in this list. + Tasks in the Task Queue are not shown here. + + A task marked as queued in the Task List indicated that no robot or fleet was available at the time of dispatch. + The task will be automatically assigned once resources become available. + + +.. TODO: Think about the following: +.. Do we want to have it here, which will make this page too long. Or do we want to have a single page per feature. +.. Single page per feature makes more sense to me as we can explain each feature in details and show it with pictures and videos. + + +Map Page +######## + +The Map Page provides a 2D top-down view of the environment in which robots and fleets operate. +It represents the physical space and defines where robots can move and navigate. + +On this page, you can view: + +- All robots and their associated fleets. +- Waypoints that define valid robot navigation paths. +- Map levels if multiple levels exists +- Environmental resources such as doors and lifts +- Detailed information about robots and waypoints. + +.. map_visualisation +.. image:: /_static/odin_fleet/map_visualization.png + :alt: Map Page - Map visualizaton. + :width: 800px + :align: center + +When a task is dispatched to a robot or fleet, the map updates in real time, showing robot movement throughout the environment. + +.. image:: /_static/odin_fleet/map_visualization_robot_in_transit.png + :alt: Map Page - Map visualization with an active robot. + :width: 800px + :align: center + +| + +Robot's Page +############ + +The Robot's Page displays all avaialble robots, each represented by an individual card. + +.. TODO: Add another image once we have multiple robots here + +.. image:: /_static/odin_fleet/robots_list.png + :alt: Robot Page - Full list of available robots. + :width: 800px + :align: center + +Each card contains key information about a robot, including its current state (idle, charging, or executing task), connection signal strength, battery level, and current position. + +.. raw:: html + +
+
+ Robot Page - A detailed view of a single robot. + Robot Page - A detailed view of a single robot. +
+
+ +You can decommission a robot by clicking the **Decommission** button. +A confirmation prompt will appear, allowing you to either reassign the robot's active tasks to other robots or set it to an idle behavior, such as moving to a charging station. + +.. image:: /_static/odin_fleet/robot_decomission.png + :alt: Robot Page - Robot Card - Decommission a robot. + :width: 800px + :align: center + +Another important feature is the **Diagnostics** view. +When you click the Diagnostics button, a dedicated page opens where you can inspect detailed information about the robot, including ROS2 topics, current state, battery status, and other system data. +This provides a clear interface for monitoring and troubleshooting robot behavior. + +.. image:: /_static/odin_fleet/diagnostics_page.png + :alt: Diagnostics Page. + :width: 800px + :align: center + +| + +.. TODO: Info regarding scanning a map and uploading it to the dashboard. + +.. TODO: Adding/removing a robot to a fleet. + +Doors and Lifts +############### + +The Doors and Lifts page provides two separate lists: one for doors and one for lifts. + +The doors list includes information such as the door ID, name, and control system details. +The lifts list contains the relevant information required to manage and monitor lift resources. + +This page not only allows you to monitor doors and lifts, but also to control them. +You can configure rules that define when doors should open or when lifts should move, based on specific robot actions or system conditions. + +.. warning:: + + These features are not yet fully implemented or tested. + Use them at your own risk. + +.. TODO: Adding picture here for more clarity. + Once we have this features implemented and the means to test them, show it, and explain it in more details. + +Configuration +############# + +The Configuration Page allows you to configure the web dashboard and manage your personal settings. + +You can update your profile details, including your profile name, email, and password. + +It also allows you to switch between light and dark mode. + +.. image:: /_static/odin_fleet/config_page.png + :alt: Configuration Page. + :width: 800px + :align: center + +| + +Feedback +######## + +The Feedback Page allows you to quickly report issues to the team. + +If you encounter problems with the dashboard, robot control, or other system resources, you can use this page to submit a report. + +Provide your contact information, select the affected robot or software, and describe the issue in detail. + +Our team will respond as soon as possible. + +.. image:: /_static/odin_fleet/feedback_page.png + :alt: Feedback Page. + :width: 400px + :align: center + +.. note:: + + You can also contact us directly through our contact email: `Ubiquity Robotics support `_. + +---- + +Next Steps +########## + +With an understanding of the core concepts and features of the Web Dashboard, you can now start using it to manage your own robot fleets. + +To contribute to OdinFleet or customize it for your own configuration, reach out to us at `Ubiquity Robotics support `_. + +.. TODO: Uncomment this when the advanced guide is out. + +.. To contribute to OdinFleet or customize it for your own configurations, continue to the advanced guide: + +.. See :doc:`./odin_fleet_advanced`. diff --git a/docs/odin_fleet/odin_fleet_intro.rst b/docs/odin_fleet/odin_fleet_intro.rst new file mode 100644 index 0000000..38e7f93 --- /dev/null +++ b/docs/odin_fleet/odin_fleet_intro.rst @@ -0,0 +1,64 @@ +Introduction to OdinFleet +========================= + +General Overview +################ + +**OdinFleet is an application built on top of OpenRMF (Open Robot Middleware Framework)**. +**OpenRMF** is an open-source framework designed to coordinate multiple robots and automation systems in shared environments. + +OdinFleet provides a user-friendly interface for traffic managements, scheduling, and interoperability. +This enables robots from different vendors to operate together without collisions or resource conflicts. +Through our custom web dashboard, it offers clear system visibility and simplifies interaction with the entire fleet. + +By utilizing OpenRMF's APIs, OdinFleet serves as a practical tool for monitoring and controlling multiple robot fleets while improving communication between users and systems. +It uses RMW Zenoh to ensure fast and efficient communication across all components. + +Managing multiple robots has never been easier. + + +Web Dashboard +############# + +**OdinFleet's Web Dashboard** is a custom web application that allows users to authenticate, monitor system state, and perform actions from a single interface. + +Its goal is to provide a clear and accessible way to interact with robot fleets and automation systems without dealing with multiple backend tools. +By combining controls and system data in one place, it simplifies overall fleet management. + +The dashboard enables visualization of all robot fleets and their tasks, supports task dispatching and cancellation, and provides a live map view showing each robot's position within the environment. + +It gives centralized, real-time control over multiple robot operating in the same space. + + +Fleet Manager +############# + +The **Fleet Manager** acts as the bridge between OdinFleet and individual robot fleets. +It translates OdinFleet commands into vendor-specific instructions for each robot. +It collects status updates, and reports back to the system. +By doing so, it enables coordinated operation across heterogeneous fleets, ensures safe navigation, and allows multiple robots to share tasks and resources efficiently within the same environment. + + +RMW Zenoh +######### + +RMW Zenoh is the communication layer used by OdinFleet to enable fast and efficient data exchange between robots and the system. +It provides low-latency, scalable messaging across distributed components, even ii complex network setups. +This ensures reliable real-time communication between fleets, services, and users. + + +Extra Resources +############### + +To learn more about OpenRMF, ROS2, and Zenoh consider the following resources: + +- `OpenRMF Website `_ +- `OpenRMF Official Documentation `_ +- `ROS2 Jazzy Documentation `_ +- `Zenoh Official Documentation `_ + +Next Steps +########## + +Get started with our **Web Dashboard** by following the documentation: :doc:`./odin_fleet_guide`. +It goes through the key features for monitoring and controlling robots through the dashboard. diff --git a/docs/requirements/workstation.rst b/docs/requirements/workstation.rst index 35c77b0..5edd444 100644 --- a/docs/requirements/workstation.rst +++ b/docs/requirements/workstation.rst @@ -42,16 +42,16 @@ Setting up the Desktop Workstation This section assumes that you are already following the **Requirements for a Workstation** section. We will not cover how to install Ubuntu 24.04 itself, since there are many good guides available. -Instead, here are some usefull resources: +Instead, here are some useful resources: - `Download Ubuntu 24.04 Desktop `_ -- `Instalation Guide for Ubuntu 24.04 `_ +- `Installation Guide for Ubuntu 24.04 `_ Once Ubuntu 24.04 is installed and configured, you can proceed with setting up **ROS 2 Jazzy**. We recommend following the official ROS 2 installation guide: -- `ROS 2 Jazzy Instalation Guide `_ +- `ROS 2 Jazzy Installation Guide `_ This will walk you through the step-by-step installation process. @@ -95,8 +95,8 @@ Something like this: Codename: noble -Testing ROS 2 Instalation -------------------------- +Testing ROS 2 Installation +-------------------------- To verify ROS 2 is installed correctly and check its version, run: @@ -150,6 +150,109 @@ You should see something like this: If you see a list of topics, your workstation is successfully connected and ready to use. + +Zenoh Setup +########### + +Zenoh is a communication middleware that enables efficient data exchange between distributed systems, such as your workstation and robot. It is particularly useful for robotics because it handles unstable network connections (like Wi-Fi) much better than the default ROS 2 middleware. + +Installation Prerequisites +-------------------------- + +Ensure the Zenoh RMW is installed on your workstation. + +.. code-block:: bash + + sudo apt update + sudo apt install ros-jazzy-rmw-zenoh-cpp -y + +.. note:: + + Ensure your workstation and the robot are running the same version of ``ros-jazzy-rmw-zenoh-cpp``. + + +Establishing the Connection +--------------------------- + +To connect your workstation to the robot, you will manually configure the ROS 2 environment in your terminal to act as a Zenoh Client. + +Step 1: Prepare the Robot +~~~~~~~~~~~~~~~~~~~~~~~~~ + +SSH into your robot following the :doc:`../driving/connecting` guide and ensure the Zenoh Router is running. This acts as the bridge for your connection. + +**Verify the Router is Running**: Open a new terminal window on the robot (SSH in again) and run: + +.. code-block:: bash + + pgrep -a zenoh + +You should see output similar to ``[PID] rmw_zenohd``. If you see nothing, the router is not running. + + +Step 2: Configure Workstation Terminal +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Open a new terminal on your computer. Run the following commands to configure this specific terminal session to connect to the robot. + +.. important:: + + The ``ROS_DOMAIN_ID`` on your workstation **must match** the one set on the robot (the default is ``0``). If they do not match, the workstation will not see any topics even if the Zenoh connection is established. + +.. code-block:: bash + + # 1. Select Zenoh as the middleware + export RMW_IMPLEMENTATION=rmw_zenoh_cpp + + # 2. Set the Domain ID (Must match the robot) + export ROS_DOMAIN_ID=0 + + # 3. Disable local multicast (forces direct connection) + export ZENOH_SCOUT_MULTICAST_ENABLED=false + + # 4. Configure the connection to the robot (Replace ) + export ZENOH_CONFIG_OVERRIDE='mode="client";connect/endpoints=["tcp/:7447"]' + + +Step 3: Verify Connection +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Once connected, you can run standard ROS2 tools from your workstation. + + +Keyboard Teleoperation +********************** + +To drive the robot using your keyboard: + +.. code-block:: bash + + ros2 run teleop_twist_keyboard teleop_twist_keyboard + + +Visualization and Plotting +************************** + +To view sensor data: + +.. code-block:: bash + + rviz2 + + +Disconecting +------------ + +To return your terminal to its default local state, +simply close the terminal window or unset the configuration variables: + +.. code-block:: bash + + unset RMW_IMPLEMENTATION + unset ZENOH_SCOUT_MULTICAST_ENABLED + unset ZENOH_CONFIG_OVERRIDE + + Next Steps ########## diff --git a/docs/troubleshooting/hardware/motor_parameters.rst b/docs/troubleshooting/hardware/motor_parameters.rst new file mode 100644 index 0000000..c0484fa --- /dev/null +++ b/docs/troubleshooting/hardware/motor_parameters.rst @@ -0,0 +1,107 @@ +Configuring Motor Parameters +============================ + +.. warning:: + + **ADVANCED USERS ONLY** + + This section is intended for advanced users who need to fine-tune the motor performance of the Magni robot. + Incorrectly configuring these parameters can lead to unstable and potentially dangerous situations, hardware damage, or safety hazards. + Do not modify these settings unless you fully understand what they do and their impact. + +.. danger:: + + **CRITICAL SAFETY REQUIREMENT: WHEELS OFF THE GROUND** + + When performing any operations or tuning motor parameters, the robot's wheels **MUST NEVER** touch the ground. + Support the robot's frame so that the wheels are floating and can spin without moving the robot itself. + Failure to do so can result in the robot "going wild" and causing injury or damage if parameters are set incorrectly. + +Overview +######## + +The Magni robot's motor control system (the ``/mcb`` node) uses several parameters to define its movement characteristics. +Because tuning involves changing internal control coefficients, a specific workflow must be followed to ensure the system remains under control. + +Recommended Workflow +#################### + +To safely tune the robot, you should first disable the automatic wheel locking (auto-enable) and use manual service calls to test your changes. + +1. Disable Auto-Enable +---------------------- + +Before you start, it is best to ensure the robot will not automatically attempt to drive or lock its wheels on boot/reset. + +.. code-block:: bash + + ros2 param set /mcb drive.general.auto_enable false + +2. Modify Parameters +-------------------- + +Set your desired parameters using ``ros2 param set``. For example, to change the Proportional coefficient of the position control: + +.. code-block:: bash + + ros2 param set /mcb drive.pid.position.p 2000 + +3. Reset the MCB +---------------- + +For most parameters to take effect, the MCB must be reset. Press the **middle tactile switch** located in the upper left of the Motor Control Board PCB. + +.. image:: /_static/driving/teleop/restart_MCB.jpg + :alt: Restart the MCB button + :width: 400px + :align: center + +4. Enable the Drive +------------------- + +Once the MCB has been reset, you must manually enable the drive system. + +First, ensure you have pressed the **upper right-most physical switch** . +Or you can also execute the following service call: + +.. code-block:: bash + + ros2 service call /mcb/enable_drive std_srvs/srv/SetBool "{data: true}" + +If the wheels are off the ground, they should now respond to the new control parameters. + +Commonly Modified Parameters +############################ + +All parameters below are under the ``/mcb`` node. + +Kinematic settings +------------------ + +These define the physical limits of the robot's motion. Increasing acceleration makes the robot more responsive but may cause jerking or slipping. + +- ``drive.movement.max_lin_accel_mm_s2``: Maximum linear acceleration (default is often 500). +- ``drive.movement.max_rot_accel_mrad_s2``: Maximum rotational acceleration. +- ``drive.movement.max_lin_speed_mm_s``: Maximum linear speed. + +Motor Calibration +----------------- + +If your motors are not "locking" or holding position properly during startup calibration, you may need to increase the calibration current. + +- ``drive.motors.encoder_calib_current_A``: The current used during encoder calibration. + + .. tip:: + If you find that the calibration fails to lock the motors sometimes, try increasing this value (e.g., to ``2.5``). + +PID Position Control +-------------------- + +These coefficients control the PD position controller for the motors. + +- ``drive.pid.position.p``: Proportional coefficient. +- ``drive.pid.position.d``: Derivative/Differential coefficient. + +.. note:: + + Changes made via ``ros2 param set`` are persistent and will remain set until changed again. Once you have found the ideal settings, you should ensure they are correctly reflected in your permanent configuration files if necessary. \ No newline at end of file diff --git a/docs/troubleshooting/troubleshooting_tips.rst b/docs/troubleshooting/troubleshooting_tips.rst new file mode 100644 index 0000000..041d60e --- /dev/null +++ b/docs/troubleshooting/troubleshooting_tips.rst @@ -0,0 +1,47 @@ +Quick Troubleshooting Tips +========================== + +If you run into common startup or connectivity issues, try the following quick fixes. + +Magni 6 Mini +############ + +.. dropdown:: **On/off switch is not working** + + The issue may be caused by an intermittent internal hardware contact. + Try pressing the switch firmly, or give the switch area a light tap. + +General +####### + +.. dropdown:: **Motors/robot is not moving** + + If the robot's wheels do not lock automatically, manually lock them by pressing the button on the Motor Control Board (MCB). + It's the button closest to the wire connector. + + .. image:: /_static/driving/teleop/enable_MCB.jpg + :alt: Enable the MCB button + :width: 400px + + | + + If the wheels are locked but the robot still does not respond, restart the MCB by pressing the middle button. + + .. image:: /_static/driving/teleop/restart_MCB.jpg + :alt: Restart the MCB button + :width: 400px + + | + + After that, make sure wheels are locked again, and try driving the robot. + If that does not work, restart the robot and try again. + +.. dropdown:: **Robot cannot find the local network** + + First, list nearby Wi-Fi networks from the robot: + + .. code-block:: bash + + nmcli device wifi list + + If your local Wi-Fi (SSID) does not appear in the list, restart the robot and try connecting again. \ No newline at end of file diff --git a/docs/unboxing/unboxing_midi.rst b/docs/unboxing/unboxing_midi.rst index 446c03d..aac37e3 100644 --- a/docs/unboxing/unboxing_midi.rst +++ b/docs/unboxing/unboxing_midi.rst @@ -1,9 +1,123 @@ -Unboxing and Setting Up the Magni 6 Midi -======================================== +Unboxing Magni 6 MIDI +==================== -.. image:: /_static/models/magni6_midi_2WD.png - :alt: Magni 6 Midi - :width: 400px - :align: center +This guide covers the unboxing and initial setup of the Magni 6 MIDI robot. -**THE CONTENT FOR THIS ROBOT IS COMING SOON IF YOU NEED ANY SPECIFIC INFORMATION CONTACT:** `Ubiquity Robotics support `_ +---- + +What's in the Box? +################## + +When you first open your Magni 6 MIDI, please verify that you have received the following components: + +- **Magni 6 MIDI Chassis** +- **Battery Brackets:** Designed for larger batteries (FG20721). +- **Wire Harness:** Configured for standard connection. +- **Documentation & Quick Start Guide** + +---- + +Battery Installation +#################### + +The Magni 6 MIDI is designed to also use high-capacity 33Ah batteries. Please ensure you are using the correct battery type. + +Battery Specifications +---------------------- + +The recommended battery for this model is the **FG20721**. + +.. note:: + When ordering batteries, ensure they have **6.35mm (or 6.4mm) FASTON terminals**. Some batteries come with smaller 4.75mm terminals, which are not compatible with the standard Magni wire harness. + +.. image:: /_static/unboxing/battery_type.jpg + :alt: FG20721 Battery Type + :width: 400px + :align: center + +Preparing the Battery Bay +------------------------- + +Before installing the batteries, ensure the brackets are correctly positioned in the battery bay. + +.. image:: /_static/unboxing/battery_bay_brackets.jpg + :alt: Battery Bay Brackets + :width: 600px + :align: center + +Installing the First Battery +---------------------------- + +Place the first battery into the bay as shown below. + +.. image:: /_static/unboxing/one_battery_sitting_in_the_battery_bay.jpg + :alt: Single battery in bay + :width: 600px + :align: center + +Installing the Second Battery +----------------------------- + +Add the second battery alongside the first. + +.. image:: /_static/unboxing/batteries_sitting_in_the_battery_bay.jpg + :alt: Both batteries in bay + :width: 600px + :align: center + +---- + +Wiring and Connections +###################### + +.. warning:: + + **CRITICAL BATTERY SAFETY:** + + * **Red Terminals:** The wire harness terminals with **red end termination** MUST be connected only to the battery terminal that is **RED** and currently free. + * **Black Terminals:** The wire harness terminals with **black end termination** MUST be connected only to the battery terminal that is **BLACK** and currently free. + + Failure to match these correctly will cause a short circuit and potentially damage the electronics. + +Series Connection (24V) +----------------------- + +The batteries must be connected in series to provide the required 24V power. Use the provided diagrams for reference. + +.. important:: + Ensure the batteries are connected in **series** (Positive of one battery to Negative of the other) as shown in the diagrams below to achieve 24V. Do NOT connect them in parallel. + +.. image:: /_static/unboxing/batt_to_batt_series_connction_wires.jpg + :alt: Battery to Battery Series Connection Wires Diagram + :width: 800px + :align: center + +.. image:: /_static/unboxing/connecting_the_batterie_in_series.jpg + :alt: Connecting the batteries in series - Step 1 + :width: 600px + :align: center + +.. image:: /_static/unboxing/connecting_the_batteries_in_series2.jpg + :alt: Connecting the batteries in series - Step 2 + :width: 600px + :align: center + +.. image:: /_static/unboxing/batt_to_batt_series_connection.jpg + :alt: Completed Series Connection + :width: 600px + :align: center + +---- + +Final Check +########### + +Before powering on, verify all connections and ensure the robot is on a flat surface. + +Next Steps +########## + +Once unboxed and powered, proceed to :doc:`../driving/connecting` to start using your robot. + +.. TODO: Rearrange images based on user feedback. +.. TODO: Add detailed descriptions for each step. diff --git a/docs/unboxing/unboxing_mini.rst b/docs/unboxing/unboxing_mini.rst index 7e7cae9..28d8ee6 100644 --- a/docs/unboxing/unboxing_mini.rst +++ b/docs/unboxing/unboxing_mini.rst @@ -159,6 +159,9 @@ The Magni 6 Mini uses two **lead-acid batteries**. Ensure the Magni 6 Mini's these two batteries are safely installed and charged before powering on. For for exact instructions on how to charge the batteries before adding them to ther robot: :doc:`../requirements/batteries`. +.. note:: + When ordering batteries, ensure they have **6.35mm (or 6.4mm) FASTON terminals**. Some batteries come with smaller 4.75mm terminals, which are not compatible with the standard Magni wire harness. + 1. Inspect the Batteries ------------------------ diff --git a/requirements.txt b/requirements.txt index c88f635..c4f085c 100644 --- a/requirements.txt +++ b/requirements.txt @@ -2,4 +2,5 @@ rinohtype pigments gitpython sphinx -sphinx-rtd-theme \ No newline at end of file +sphinx-rtd-theme +sphinx-design \ No newline at end of file