Configuration¶
Everything xparo_ros needs is passed as ROS 2 parameters when you start
it. Only the first two are required.
Build your command¶
Fill in the boxes and copy the result. The builder only adds the settings you change from their defaults.
The same thing written by hand:
ros2 launch xparo xparo_launch.py \
xparo_project_id:=<your-project-id> \
xparo_secret_key:=<your-secret-key>
The node is named /xparo_ros. The launch file can also start a ROS
bag recorder for you (record_bags:=true).
ros2 run xparo xparo_ros --ros-args \
-p xparo_project_id:=<your-project-id> \
-p xparo_secret_key:=<your-secret-key>
The node is named /xparo.
Main settings¶
Parameter |
Default |
What it does |
|---|---|---|
|
(none) |
Required. The project to join. Copy it from the Dashboard page (Project Key (websocket routing id)) or from the Robots Fleet Add a robot dialog. |
|
(none) |
Required for the first connection. A secret key generated on the Dashboard page. After the first connection the robot uses its own saved credential instead (see What the robot keeps on its own disk), and only falls back to this key if that credential is rejected. |
|
|
Which task stages this robot accepts: |
|
|
|
|
|
How the robot talks to the server. See Connection types below. |
|
|
Launch file only: |
|
|
Who shows the project’s approved ads on the robot’s screen:
|
Warning
Quote off (and any value like on, yes, no, true,
false) when you pass it on the command line. ROS 2 reads a bare
off as the boolean false and the node then stops with
InvalidParameterTypeException: ... expecting type 'STRING'.
ros2 launch xparo xparo_launch.py ... "xparo_ads_display:='off'"
ros2 run xparo xparo_ros --ros-args ... -p "xparo_ads_display:='off'"
Connection types¶
Value |
Behaviour |
|---|---|
|
Use this. A permanent connection; the dashboard can reach the robot instantly. If it drops, the robot reconnects by itself every 5 seconds and re-syncs. |
|
Like |
|
No WebSocket at all: the robot polls the server over HTTPS. It still syncs trees and tasks and uploads its data, but dashboard commands cannot reach it: Run now, terminal, files, teleop and the other Robots Fleet tools need a WebSocket connection. |
Whatever the type, the robot sends its 30-second heartbeat as an HTTPS request, so it needs outgoing HTTPS (port 443) as well as the WebSocket.
A config file instead of parameters¶
xparo_ros also reads ~/xparo_config.json from the home directory of
the user it runs as, and uses its values as the defaults for these
parameters: xparo_project_id, xparo_secret_key,
xparo_connection_type, xparo_environment, xparo_stage,
xparo_transport, tethered_channels_config_path and
xparo_ads_display.
{
"xparo_project_id": "<your-project-id>",
"xparo_secret_key": "<your-secret-key>",
"xparo_stage": "development"
}
ros2 run xparo xparo_ros
The node logs ALERT: xparo_config.json file found in home directory when
it uses the file.
Important
The file only works with ros2 run. The launch file always passes its
own defaults for every parameter (an empty project ID, the production
stage, and so on), and parameters passed on start-up win over the file.
With ros2 launch, pass the values as launch arguments instead.
Advanced settings¶
You rarely need these. They decide where synced files are written on the robot; Synced files and folders explains what each file is for.
Parameter |
Default with |
Default with |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
not a launch argument |
|
|
|
|
|
empty |
empty |
<share> is the package’s install folder, usually
~/xparo_ws/install/xparo/share/xparo. Print it with
ros2 pkg prefix xparo (then add /share/xparo).
xparo_transport is always django_ws for a robot that talks to
xparo.in. The other value, tethered_tcp, is for vehicles connected to a
topside computer by a tether cable with no internet access; it is not covered
in these docs.
What the robot keeps on its own disk¶
Besides the synced files above, xparo_ros keeps its own state next to
its Python code, in <workspace>/install/xparo/lib/python3.X/site-packages/
(X is your Python version):
Path (under |
What it is |
|---|---|
|
The robot’s own credential, saved after the first connection
(readable only by its owner). Delete it to make the robot join with
|
|
The folder the Robots Fleet Files tool browses, uploads to and downloads from. |
|
Logs, messages waiting to be sent, and ad data for that project. |
Note
This folder is inside the build output, so rm -rf install or a clean
rebuild deletes it. The robot then simply joins again with
xparo_secret_key on its next start, and shows up as the same robot
because its device ID comes from the MAC address.
