XPARO ROS2 Integration
======================
This page explains how to use **XPARO with ROS2**.
The XPARO ROS2 node allows robots to communicate with the XPARO platform using ROS topics.
It connects your robot to the XPARO server and enables:
- Sending questions or commands
- Receiving responses from the XPARO engine
- Sending task updates
- Recording ROS bag files automatically
- Uploading logs to the XPARO server
The node is already implemented and ready to use.
Users only need to **run the node and use the provided ROS topics.**
---
Running the XPARO ROS2 Node
---------------------------
Run the node normally using ROS2:
.. code-block:: bash
ros2 run xparo_ros xparo_node
Or using a launch file:
.. code-block:: bash
ros2 launch xparo_ros xparo_launch.py
After starting the node it will automatically connect to the XPARO server.
---
ROS Parameters
--------------
The node uses several parameters to connect to the XPARO platform.
These parameters are usually set inside a **launch file**.
Parameters
^^^^^^^^^^
**xparo_project_id**
Your XPARO project identifier.
Example:
::
xparo_project_id = "project_01"
This tells the node which project on the XPARO server it belongs to.
---
**xparo_secret_key**
Secret key used to authenticate the robot with the server.
Example:
::
xparo_secret_key = "abc123secret"
Do not share this key publicly.
---
**xparo_connection_type**
Defines how the robot communicates with the server.
Available options:
- ``websocket`` (recommended)
- ``rest``
Example:
::
xparo_connection_type = "websocket"
---
**BAG_DIR**
Directory where ROS bag recordings will be stored.
Example:
::
BAG_DIR = "/home/robot/ros_bags"
Recorded bag files will automatically be uploaded to the XPARO server when possible.
---
ROS Topics
----------
The node communicates using standard ROS topics.
Topics are used to send questions to the XPARO engine and receive responses.
---
Topic: /xparo/ask
^^^^^^^^^^^^^^^^^
This topic is used to **send a question or command to XPARO**.
Type:
::
std_msgs/String
Publish a text message.
Example:
.. code-block:: bash
ros2 topic pub /xparo/ask std_msgs/String "data: 'Hello robot'"
Expected Behavior
^^^^^^^^^^^^^^^^^
The message will be sent to the XPARO engine.
The engine processes the request and returns a response.
The response will appear on:
::
/xparo/response
---
Topic: /xparo/response
^^^^^^^^^^^^^^^^^^^^^^
This topic publishes responses from the XPARO engine.
Type:
::
std_msgs/String
Example output:
::
data: "Hello, how can I help you?"
Robots can use this message for:
- text-to-speech
- display on screen
- UI dashboards
- logging
Example subscriber:
.. code-block:: bash
ros2 topic echo /xparo/response
---
Topic: /xparo/json
^^^^^^^^^^^^^^^^^^
This topic publishes raw JSON messages from XPARO.
Type:
::
std_msgs/String
Example output:
::
data: {"intent":"navigate","target":"table_4"}
This topic is useful for applications that need structured data.
Example:
- UI dashboards
- navigation systems
- custom robot logic
---
Topic: /xparo/task_updates
^^^^^^^^^^^^^^^^^^^^^^^^^^
This topic is used to send **task updates** to the XPARO server.
Type:
::
std_msgs/String
The message must contain JSON.
Example:
.. code-block:: bash
ros2 topic pub /xparo/task_updates std_msgs/String \
"data: '{\"task\":\"delivery\",\"status\":\"completed\"}'"
Expected Behavior
^^^^^^^^^^^^^^^^^
The update is stored in the XPARO database and can be viewed from the dashboard.
This allows the server to track robot activities.
---
Typical Workflow
----------------
1. Start the XPARO ROS2 node
::
ros2 run xparo_ros xparo_node
2. Send a question
::
ros2 topic pub /xparo/ask std_msgs/String "data: 'Hello robot'"
3. Receive the response
::
ros2 topic echo /xparo/response
4. Send task updates
::
ros2 topic pub /xparo/task_updates std_msgs/String "data: '{\"task\":\"delivery\",\"status\":\"completed\"}'"
---
ROS Bag Recording
-----------------
The XPARO ROS node automatically records ROS bag files.
Recorded data includes:
- robot telemetry
- ROS topics
- system events
Files are saved inside:
::
BAG_DIR
Example:
::
/home/robot/ros_bags/
The node automatically uploads completed recordings to the XPARO server.
This feature is useful for:
- debugging
- remote diagnostics
- system analysis
---
Checking Available Topics
-------------------------
To see all available topics:
.. code-block:: bash
ros2 topic list
You should see:
::
/xparo/ask
/xparo/response
/xparo/json
/xparo/task_updates
---
Troubleshooting
---------------
Node does not start
^^^^^^^^^^^^^^^^^^^
Make sure the package is installed correctly.
::
ros2 pkg list | grep xparo_ros
---
No response from /xparo/response
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Check the following:
- project_id is correct
- secret_key is correct
- robot has internet access
---
Topics not visible
^^^^^^^^^^^^^^^^^^
Check if the node is running.
::
ros2 node list
You should see:
::
/xparo
---
Support
-------
Website
::
https://xparo-website.onrender.com
GitHub
::
https://github.com/lazyxcientist
Contact
::
xpassistantpersonal@gmail.com
.. raw:: html
.. raw:: html
.. raw:: html
