Nodes and Launch Files

This page gives the packages of the ROS 2 workspace, each node with its parameters and each launch file with its arguments. It also gives the environment settings of ROS/Env and the tools of ROS/Tools.

One Polaris session. The node sim_bridge reads the three local sockets of the simulator and gives the data as topics, services and one action. Open the diagram

The ROS 2 bridge is the node sim_bridge. It connects to the three local sockets of a simulator: the Sensor Stream, the Vehicle Bridge and the Simulator Control Channel. The simulator is the game or the node core_sim, which runs ACRES Core behind the same sockets. Topics and Services and Actions give the interfaces of the bridge.

Item	Type	Function
Packages	Table	The packages of the workspace ROS.
sim_bridge	Node	The ROS 2 bridge.
core_sim	Executable	ACRES Core behind the three sockets of the game.
dbw_demo_driver	Node	Drives the Polaris along a route with drive-by-wire commands.
lab_stubs	Node	Substitutes for the inputs of the path follower of the lab.
core_bench	Executable	Measures the rates of ACRES Core behind the bridge.
odom_path	Node	Makes a path for RViz from the odometry.
fake_polaris	Node	Publishes a synthetic LiDAR cloud without a simulator.
sim_bridge.launch.py	Launch file	The bridge, the Polaris description and RViz.
core_sim.launch.py	Launch file	core_sim and the bridge.
lab_follower.launch.py	Launch file	The path follower of the lab with lab_stubs.
description.launch.py	Launch file	The Polaris description.
bag_replay.launch.py	Launch file	Plays a bag of the real Polaris into RViz.
fake_polaris.launch.py	Launch file	The description, fake_polaris and RViz.
Files of ROS/Env	Table	The environment, the fence and the colcon options.
Variables of the Fence	Table	Each setting of the DDS loopback fence.
Other Variables	Table	The variables that the scripts and the tests read.
Default Ports	Table	The ports of the launch files and of core_sim.
Tools of ROS/Tools	Table	The checks and the helper scripts.

WARNING

Start each node in a shell that has the DDS loopback fence: source ROS/Env/setup_env.sh. The nodes dbw_demo_driver and lab_stubs send drive-by-wire commands. Outside the fence, a command can move the real Polaris.

Packages

The workspace is the folder ROS. The command colcon list shows 6 packages in the public repository.

Package	Build Type	Content
acres_interfaces	ament_cmake	15 messages and 5 services of the simulator. Refer to Messages.
acres_sim	ament_cmake	The node sim_bridge (C++), the nodes dbw_demo_driver and lab_stubs (Python), the J1939 codec, two launch files.
acres_core_sim	ament_cmake	The executable core_sim (C++, with ACRES Core compiled in), core_bench, one launch file.
acres_description	ament_python	The Polaris description (xacro, meshes, RViz configuration), the nodes odom_path and fake_polaris, three launch files.
ds_dbw_msgs	ament_cmake	The Dataspeed drive-by-wire messages, release 2.3.11, in ROS/vendor. 45 messages and 27 field types.
rslidar_msg	ament_cmake	The RoboSense packet message RslidarPacket, in ROS/vendor. No node of the workspace uses it.

The package purdue_ranger is not in the repository. It contains the URDF file of the real Polaris. The file polaris_ranger.urdf.xacro of acres_description includes that URDF file. Build the ROS 2 Workspace tells you which launch files need the package.

The package acres_sim also installs the Python module acres_sim.j1939 and the C++ headers acres_sim/*.hpp. Wheel and CAN Signals gives the CAN signals that the codec encodes.

Nodes

sim_bridge

Package acres_sim. The ROS 2 bridge. One process connects to the sockets of one vehicle or of all agents of a session.

The node publishes the topics of the vehicle and forwards each command to the simulator immediately. With a control port, the node also gives the services and the action of the simulator control channel in the root namespace. The node connects again automatically when a socket closes. It accepts only a loopback address as host.

A separate thread publishes the LiDAR clouds and the camera images. Its queue holds 4 frames. The node drops a frame when the queue is full and counts the frame in the statistics.

Name	Type	Unit	Default	Description
host	string		127.0.0.1	The address of the simulator. The node accepts only a loopback address.
sensor_port	integer		5601	The port of the sensor stream (-SensorStream=).
rl_port	integer		5556	The port of the vehicle bridge (-RlPort=). 0 = no connection.
control_port	integer		5600	The port of the simulator control channel (-SimControl=). 0 = no services.
can_udp_port	integer		0	The UDP port of the CAN bus of the Maxxum (-RlCanUdp=). 0 = no CAN topics.
vehicle	string		auto	polaris, maxxum or auto. With auto, the first message of the sensor stream selects the topic set.
agents	string		empty	Empty: one vehicle from the ports above. auto: all agents of the session, from the control channel.
publish_clock	boolean		true	Publishes /clock. Only one bridge of a session can publish the clock.
frame_prefix	string		empty	A prefix for the TF frames, for example polaris2/.
utm_frame	string		utm	The parent frame of the odometry and of the transform.
stats_file	path		empty	A JSON file with the transport statistics. The node writes it at shutdown.
barrier_timeout_s	number	s	5.0	The time that a step waits for the barriers after the reply of the simulator.
control_timeout_s	number	s	30.0	The time limit of one request on the control channel. A step adds 0.2 s for each step.
speed_kp	number	1/(m/s)	0.8	Maxxum speed loop: pedal for each m/s of speed error.
speed_ki	number	1/m	0.4	Maxxum speed loop: pedal for each metre of accumulated error.
max_speed_mps	number	m/s	3.4	Maxxum: the limit of speed_cmd.
cmd_timeout_s	number	s	0.5	Maxxum: the guidance stops after this simulation time without a command.

With agents:=auto, agent 0 uses the namespace of the node and no frame prefix. Each other agent gets a node sim_bridge in the namespace <name> and the frame prefix <name>/. The statistics file of such an agent is <stats_file>_<name> before the file extension.

ROS 2 CLI

ros2 run acres_sim sim_bridge --ros-args \
    -p sensor_port:=5601 -p rl_port:=5556 \
    -p control_port:=5600

[sim_bridge]: sim_bridge: sensor stream 127.0.0.1:5601, JSON bridge 127.0.0.1:5556, vehicle auto, frame prefix '', /clock on
[sim_bridge]: simulator control: waiting for the game's control channel on 127.0.0.1:5600
[sim_bridge]: simulator control: connected to 127.0.0.1:5600 (protocol 1, map V03ACRE, state 1, lockstep off, step 103, 1 agents)
[sim_bridge]: publishing the polaris topics
[sim_bridge]: connected to polaris (polaris): LiDAR 1800 x 32 at 10 Hz, camera None x None at 0 Hz, INS 100.0 Hz

This session uses core_sim, which has no camera. The statistics line, each 30 s:

[sim_bridge]: stream: clock 120.0 Hz 0.0 MB/s latency p50 0.0 p95 0.1 ms; ins 100.0 Hz 0.0 MB/s latency p50 0.1 p95 0.2 ms; lidar 10.0 Hz 9.2 MB/s latency p50 0.3 p95 1.2 ms

All agents of one session:

ROS 2 CLI

ros2 run acres_sim sim_bridge --ros-args \
    -p agents:=auto -p control_port:=5600

[sim_bridge]: agent 0 'polaris' (polaris): namespace /, sensor stream 5601, JSON bridge 5556, CAN UDP 0
[sim_bridge]: agent 1 'polaris2' (polaris): namespace /polaris2, sensor stream 5611, JSON bridge 5566, CAN UDP 0

core_sim

Package acres_core_sim. The executable runs the Polaris of ACRES Core behind the three sockets of the game. It is not a ROS 2 node. The node sim_bridge connects to it in the same way as to the game.

The executable has no camera. It runs in real time, at a rate factor or in lockstep. Stop it with Ctrl+C. It then writes a line with the number of steps and the speed.

Name	Type	Unit	Default	Description
--root	path		repository root	The repository that contains Acres/Content/Simulation and Core/Data.
--agents	list		polaris	The agent names, with commas between them. Each agent is one Polaris.
--sensor-ports	list		5601	The sensor stream port of each agent.
--rl-ports	list		5556	The vehicle bridge port of each agent.
--control-port	integer		5600	The port of the simulator control channel. 0 = no channel.
--lockstep	flag		off	Starts in the paused state. The world advances only on step requests.
--rate	number		1.0	The rate factor: 1 = real time, 10 = ten times real time, 0 = no limit.
--spawn	list		ICSC garage	The spawn of each agent: place:<id>, utm:<easting>:<northing>:<heading> or enu:<x>:<y>:<yaw>. Angles in degrees.
--polaris-set	string		empty	Changes of Polaris parameters: key=value;key=value.
--no-lidar	flag		LiDAR on	Disables the ray-cast LiDAR.
--lidar-threads	integer		4	The number of threads that compute the LiDAR scans.
--no-noise	flag		noise on	Disables the noise of the INS and of the LiDAR.
--episode-log	path		no log	Records an Episode Log from the start.
--max-frame-steps	integer	steps	12	The maximum number of physics steps in one pass of the loop.

When the port lists are shorter than the agent list, each next agent gets the last port plus 10. The heading of the utm spawn is clockwise from grid north. The yaw of the enu spawn is counter-clockwise from east.

ROS 2 CLI

ros2 run acres_core_sim core_sim

ACRES_CORE_SIM_READY agents=1 control=5600 lockstep=0 rate=1 world_load_s=0.52 utm_origin=500476.935,4480099.755 grid_rotation_deg=0.054092
ACRES_CORE_SIM_AGENT name=polaris sensor_stream=5601 rl_port=5556 x=-38.710 y=-140.513 yaw_deg=90.00

Two agents, ten times real time:

ROS 2 CLI

ros2 run acres_core_sim core_sim \
    --agents polaris,polaris2 --rate 10

ACRES_CORE_SIM_AGENT name=polaris sensor_stream=5601 rl_port=5556 x=-38.710 y=-140.513 yaw_deg=90.00
ACRES_CORE_SIM_AGENT name=polaris2 sensor_stream=5611 rl_port=5566 x=-32.710 y=-140.513 yaw_deg=90.00

The line at the end of a session:

ACRES_CORE_SIM_EXIT steps=42950 sim_s=357.917 wall_s=360.842 speedup=0.99 lidar_dropped=0

dbw_demo_driver

Package acres_sim. The node drives the Polaris along a route with pure pursuit on vehicle/odom. It enables the drive-by-wire, selects the gear L and sends SteeringCmd (curvature) and UlcCmd (speed) at 50 Hz. At the end of the route it stops the vehicle and disables the drive-by-wire.

The route file is a GeoJSON LineString in EPSG:32616 or a CSV file with the columns x,y or easting,northing. The node samples the route at 0.5 m.

Name	Type	Unit	Default	Description
route_file	path		empty	The route file. This parameter is necessary.
speed_mps	number	m/s	3.0	The speed on a straight path.
lookahead_m	number	m	6.0	The look-ahead distance of the pure pursuit.
max_curvature	number	1/m	0.2	The limit of the curvature command.
start_delay_s	number	s	3.0	The time after the first odometry message before the node sends commands.
start_index	integer		0	The first route point.
stop_index	integer		-1	The last route point. -1 = the end of the route.
rate_hz	number	Hz	50.0	The command rate.
use_sim_time	boolean		false	Set to true. The node then uses the clock of the simulator.

The node publishes Demo/status (std_msgs/String) and Demo/route (nav_msgs/Path, in the frame demo_route_origin).

ROS 2 CLI

ros2 run acres_sim dbw_demo_driver --ros-args \
    -p route_file:=route.csv -p speed_mps:=2.0 \
    -p use_sim_time:=true

A route file route.csv that goes 40 m to the north from the ICSC garage:

x,y
500438.1,4479970.0
500438.1,4480010.0

lab_stubs

Package acres_sim. The node gives the inputs that the path follower of the lab gets from other nodes of the real vehicle. It publishes /safety_stop (std_msgs/Bool) and /obstacle_speed_limit_mps (std_msgs/Float32) at 20 Hz. It publishes /vehicle/enable and a GearCmd each second until the reports show the correct state.

Name	Type	Unit	Default	Description
obstacle_speed_limit_mps	number	m/s	99.0	The speed limit when no event is active.
stop_schedule	string list		['']	Events at route indexes. Each event occurs one time.
gear	string		L	The gear lever: P, R, N, H, D or L.
enable_dbw	boolean		true	Sends /vehicle/enable until the drive-by-wire is on.

An event of stop_schedule has one of these formats:

Event	Effect
stop:<index>:<seconds>	A safety stop for the given time. <index>:<seconds> is the same.
limit:<index>:<to index>:<m/s>	A speed limit between two route indexes.
cap:<index>:<m/s>	Sets the parameter operator_speed_limit_mps of the follower.

ROS 2 CLI

ros2 run acres_sim lab_stubs --ros-args \
    -p "stop_schedule:=['stop:466:1.9']" \
    -p use_sim_time:=true

core_bench

Package acres_core_sim. The script starts core_sim and sim_bridge on free ports in a namespace of its own. It measures the topic rates in real time, the speed at rate factors 10, 20, 30 and without limit, and the speed in lockstep. It writes the results to a JSON file and stops only the processes that it started.

Name	Type	Unit	Default	Description
--out	path		core_bench.json	The result file. The logs go into the same folder.
--seconds	number	s	10.0	The time of each measurement.
--lidar-threads	integer		4	The number of LiDAR threads of core_sim.

ROS 2 CLI

ros2 run acres_core_sim core_bench \
    --out /tmp/bench/core_bench.json

Results with 16 processor threads. Speed = simulation time / real time.

Mode	LiDAR	Speed
Real time	on	1.0. Odometry 100 Hz, reports 50 Hz, LiDAR 10 Hz.
Rate factor 10, 20, 30	on	10.0, 20.0, 30.0. All scans arrive.
No rate limit	on	347. 9 % of the scans arrive.
No rate limit	off	400
Lockstep, 12 steps for each request	on	6.5
Lockstep, 12 steps for each request	off	93
Lockstep, 120 steps for each request	on	24
Lockstep, 120 steps for each request	off	197

odom_path

Package acres_description. The node subscribes to odom and publishes path (nav_msgs/Path). The UTM coordinates of the odometry are too large for the 32-bit numbers of RViz. The node thus puts a frame at the first position and publishes the path relative to this frame. The launch files remap the topics to vehicle/odom and vehicle/odom/path.

Name	Type	Unit	Default	Description
origin_frame	string		odom_origin	The frame at the first odometry position. The node publishes it on /tf_static.
min_spacing	number	m	0.05	The minimum distance between two poses of the path.
max_poses	integer		20000	The maximum number of poses. The node removes the oldest poses.

ROS 2 CLI

ros2 run acres_description odom_path --ros-args \
    -r odom:=/vehicle/odom \
    -r path:=/vehicle/odom/path \
    -p use_sim_time:=true

fake_polaris

Package acres_description. The node publishes a synthetic LiDAR cloud on /lidar/points without a simulator. The cloud has the layout of the real sensor: 1800 columns and 32 rings, with x, y, z and intensity. The scene is flat ground, two rows of posts and one person who walks across the lane. The node also publishes the static transform from odom to base_footprint. It reads the LiDAR pose from TF.

Name	Type	Unit	Default	Description
rate_hz	number	Hz	10.0	The rate of the cloud.
base_frame	string		base_footprint	The frame of the vehicle.
lidar_frame	string		lidar	The frame of the LiDAR.
odom_frame	string		odom	The parent frame of the parked vehicle.
walker_speed	number	m/s	1.2	The speed of the person.

ROS 2 CLI

ros2 run acres_description fake_polaris

The node waits for the transform from base_footprint to lidar. The Polaris description publishes this transform.

Launch Files

All arguments have the format name:=value. The command ros2 launch <package> <file> --show-args shows the arguments.

sim_bridge.launch.py

Package acres_sim. Starts sim_bridge for a running simulator. With vehicle:=polaris, the file also starts the Polaris description and odom_path. This needs the package purdue_ranger. With rviz:=true and vehicle:=polaris, the file also starts RViz 2.

Name	Type	Unit	Default	Description
vehicle	string		polaris	polaris, maxxum or auto. auto and maxxum start only the bridge.
sensor_port	integer		5601	The port of the sensor stream.
rl_port	integer		5556	The port of the vehicle bridge. 0 = no connection.
control_port	integer		5600	The port of the simulator control channel. 0 = no services.
can_udp_port	integer		0	The UDP port of the CAN bus of the Maxxum. 0 = no CAN topics.
agents	string		empty	Empty = one vehicle. auto = all agents of the session.
namespace	string		empty	The namespace of the vehicle.
frame_prefix	string		empty	The prefix of the TF frames, for example polaris2/.
publish_clock	boolean		true	Publishes /clock. Set to false for a second bridge.
stats_file	path		empty	The statistics file of the bridge.
rviz	boolean		false	Starts RViz 2.
rviz_config	path		polaris.rviz	The RViz configuration, from acres_description/rviz.
camera_xyz	string	m	2.745 0.606 1.887	The camera position in base_footprint.
camera_rpy	string	rad	-0.06091 0.28833 -0.04590	The camera roll, pitch and yaw.

The camera defaults are the camera mount of the simulator in sensors_polaris.json. All nodes except the bridge use the simulation time (use_sim_time).

The Polaris with the description (needs purdue_ranger):

ROS 2 CLI

ros2 launch acres_sim sim_bridge.launch.py rviz:=true

The Polaris without the description:

ROS 2 CLI

ros2 launch acres_sim sim_bridge.launch.py vehicle:=auto

The Maxxum with its CAN bus. Start the game:

Shell

Packaged/Linux/Acres.sh -VehicleDemo -Vehicle=maxxum \
    -SensorStream=5602 -RlPort=5557 \
    -RlCanUdp=5610 -SimControl=5600

Then start the bridge:

ROS 2 CLI

ros2 launch acres_sim sim_bridge.launch.py \
    vehicle:=maxxum namespace:=maxxum \
    frame_prefix:=maxxum/ sensor_port:=5602 \
    rl_port:=5557 can_udp_port:=5610

All agents of a session:

ROS 2 CLI

ros2 launch acres_sim sim_bridge.launch.py \
    vehicle:=auto agents:=auto

core_sim.launch.py

Package acres_core_sim. Starts core_sim and includes sim_bridge.launch.py with vehicle:=polaris. The file thus needs the package purdue_ranger. Without the package, start the two programs with ros2 run. With more than one agent, the file starts the bridge with agents:=auto.

Name	Type	Unit	Default	Description
lockstep	boolean		false	Starts in the paused state.
rate	number		1.0	The rate factor. 1 = real time, 0 = no limit.
spawn	string		empty	The spawn of each agent. Empty = the ICSC garage.
polaris_set	string		empty	Changes of Polaris parameters: key=value;key=value.
agents	string		polaris	The agent names, with commas between them.
sensor_port	string		5601	The sensor stream ports.
rl_port	string		5556	The vehicle bridge ports.
control_port	integer		5600	The port of the simulator control channel.
lidar	boolean		true	The ray-cast LiDAR.
lidar_threads	integer		4	The number of LiDAR threads.
noise	boolean		true	The noise of the INS and of the LiDAR.
episode_log	path		empty	Records an episode log from the start.
rviz	boolean		false	Starts RViz 2.
stats_file	path		empty	The statistics file of the bridge.

The ports are the same as the default ports of a game session. Do not run the game and core_sim on the same ports.

With purdue_ranger:

ROS 2 CLI

ros2 launch acres_core_sim core_sim.launch.py \
    lockstep:=true

Without purdue_ranger, the first shell:

ROS 2 CLI

ros2 run acres_core_sim core_sim --lockstep

The second shell:

ROS 2 CLI

ros2 run acres_sim sim_bridge

lab_follower.launch.py

Package acres_sim. Starts the nodes route_loader_node and qgis_follower_node of the lab package polaris_qgis_follower and the node lab_stubs. The lab package is not in the repository. The script ROS/Tools/build_lab_follower.sh builds it from a copy of the lab. The simulator and the bridge must be in operation before you start this file.

Name	Type	Unit	Default	Description
route_file	path			The route of the lab: GeoJSON in EPSG:32616 or CSV. This argument is necessary.
speed_mps	number	m/s	2.0	The speed of the follower.
lookahead_m	number	m	8.0	The look-ahead distance.
wheelbase_m	number	m	2.04	The wheelbase that the follower uses.
steering_ratio	number		16.0	The steering ratio that the follower uses.
operator_speed_limit_mps	number	m/s	99.0	The speed limit of the operator. 99 = no limit.
max_path_error_m	number	m	4.0	The follower stops above this path error.
min_moving_speed_mps	number	m/s	0.8	The minimum speed command while the vehicle moves.
stop_schedule	string list		['']	The events for lab_stubs.

ROS 2 CLI

source ROS/lab_ws/install/local_setup.bash
ros2 launch acres_sim lab_follower.launch.py \
    route_file:=route.geojson speed_mps:=2.0

description.launch.py

Package acres_description. Starts robot_state_publisher with the Polaris description. The description gives the static frames lidar, reolink_camera and reolink_camera_optical below base_footprint, and the visual model. The file needs the package purdue_ranger.

Name	Type	Unit	Default	Description
use_sim_time	boolean		false	Uses /clock. Set to true with a simulator or a bag.
visual	boolean		true	Includes the visual meshes.
frame_prefix	string		empty	The prefix of the TF frames.
camera_xyz	string	m	2.745 0.606 1.887	The position of reolink_camera in base_footprint.
camera_rpy	string	rad	-0.06091 0.28833 -0.04590	The roll, pitch and yaw of reolink_camera.

ROS 2 CLI

ros2 launch acres_description description.launch.py \
    use_sim_time:=true

bag_replay.launch.py

Package acres_description. Plays a bag of the real Polaris with ros2 bag play --clock. The file also starts the description, odom_path and RViz 2. It needs the package purdue_ranger.

Name	Type	Unit	Default	Description
bag	path			The folder of the bag (sqlite3). This argument is necessary.
rate	number		1.0	The rate factor of the playback.
loop	boolean		false	Plays the bag again at its end.
rviz	boolean		true	Starts RViz 2.
delay	number	s	4.0	The time before the playback starts.

WARNING

A bag of the real vehicle can contain command topics (/vehicle/*/cmd, /vehicle/enable). Play such a bag only inside the DDS loopback fence.

ROS 2 CLI

ros2 launch acres_description bag_replay.launch.py \
    bag:=/data/bags/human_20260813_172445 \
    rate:=0.25 loop:=true

fake_polaris.launch.py

Package acres_description. Starts the description, the node fake_polaris and RViz 2. The file needs the package purdue_ranger.

Name	Type	Unit	Default	Description
rviz	boolean		true	Starts RViz 2.

ROS 2 CLI

ros2 launch acres_description fake_polaris.launch.py

Environment

Files of ROS/Env

File	Function
environment.yml	The conda environment ros2: ROS 2 Humble from RoboStack, Cyclone DDS, simulation_interfaces, can_msgs, the MCAP storage, the build tools.
setup_env.sh	Activates the environment, applies the fence, sets the colcon options and loads ROS/install/setup.bash. Source it in each shell.
dds_safety.sh	Sets the variables of the fence. setup_env.sh and the conda hook source it.
cyclonedds_localhost.xml	The Cyclone DDS configuration of the fence.
install_conda_hooks.sh	Copies the two files above into the environment and adds an activation hook. An optional argument gives the environment folder.
check_dds_isolation.sh	Proves the fence. Prints PASS or FAIL. Exit code 0, 1 or 2 (not in the environment). An optional argument gives the time in seconds (default 6).
colcon_defaults.yaml	The colcon options: a symbolic-link install, the Python hints of RoboStack, BUILD_TESTING=OFF.

The packages acres_sim and acres_core_sim build their tests although BUILD_TESTING is off. The CMake options ACRES_SIM_TESTS and ACRES_CORE_SIM_TESTS control this. Their default is ON.

Variables of the Fence

The file dds_safety.sh exports these variables. The conda hook removes them when you deactivate the environment.

Name	Type	Unit	Default	Description
ROS_LOCALHOST_ONLY	integer		1	ROS 2 Humble: the middleware uses only the interface lo (127.0.0.1).
ROS_AUTOMATIC_DISCOVERY_RANGE	string		LOCALHOST	The same limit for ROS 2 Iron and later versions. Humble ignores it.
ROS_DOMAIN_ID	integer		77	The DDS domain. The UDP ports are 26660 to 26789. The real vehicle uses domain 0.
RMW_IMPLEMENTATION	string		rmw_cyclonedds_cpp	The middleware. It is the middleware of the real vehicle and it reads CYCLONEDDS_URI.
CYCLONEDDS_URI	URI		file://.../cyclonedds_localhost.xml	The Cyclone DDS configuration file.
ROS_STATIC_PEERS			not set	The script removes the variable. A peer list goes around the fence.
ROS_DISCOVERY_SERVER			not set	The script removes the variable. A discovery server goes around the fence.

The configuration file cyclonedds_localhost.xml has these settings:

Name	Type	Unit	Default	Description
General/AllowMulticast	boolean		false	No multicast. The discovery uses unicast packets only.
General/EnableMulticastLoopback	boolean		false	No multicast on the loopback interface.
Discovery/ParticipantIndex	string		auto	Each process gets the first free participant index.
Discovery/MaxAutoParticipantIndex	integer		64	The maximum index. One domain can have 65 ROS 2 processes.
Discovery/Peers/Peer	address		127.0.0.1	The only discovery peer.

The UDP ports of a domain are 7400 + 250 × domain + 10 + 2 × index and the next port. For the domain 77 and the indexes 0 to 64, the ports are 26660 to 26789.

CAUTION

Do not change ROS_DOMAIN_ID to 0 and do not remove ROS_LOCALHOST_ONLY. To use a second domain on one workstation, set ROS_DOMAIN_ID after you source setup_env.sh. Keep all other variables.

Other Variables

Name	Type	Unit	Default	Description
ACRES_ROS_ENV	string		ros2	The name of the conda environment that setup_env.sh activates.
CONDA_ROOT	path		~/miniconda3	The conda installation that setup_env.sh uses.
ACRES_ROS_ENV_PREFIX	path		~/miniconda3/envs/ros2	The environment folder for install_conda_hooks.sh.
ACRES_ROS_DDS_XML	path		adjacent to dds_safety.sh	The Cyclone DDS configuration file that dds_safety.sh uses.
COLCON_DEFAULTS_FILE	path		ROS/Env/colcon_defaults.yaml	setup_env.sh sets it for colcon.
ACRES_SIM_BRIDGE	path		installed sim_bridge	The bridge executable that the tests of acres_sim start.
ACRES_CORE_SIM	path		installed core_sim	The executable that the tests of acres_core_sim start.
POLARIS_EXTRACT	path		~/Codes/polaris/extract	The folder with the copy of the vehicle workspace, for build_lab_follower.sh.

Default Ports

The game has no default ports. The ROS 2 launch files, sim_bridge and core_sim use these defaults.

Socket	Game Option	Default	Launch Argument
Simulator control channel	-SimControl=	5600	control_port
Sensor stream	-SensorStream=	5601	sensor_port
Vehicle bridge	-RlPort=	5556	rl_port
CAN bus of the Maxxum (UDP)	-RlCanUdp=	none	can_udp_port

Tools of ROS/Tools

check_topic_parity.py

Compares a bag of the simulator with bags of the real Polaris. For each topic that both bags contain, the type, the reliability, the durability and the frame names must be the same. The tool also lists the topics that only one side has. Exit code 0 = no difference.

Name	Type	Unit	Default	Description
--sim	path list			One or more bags of the simulator. Necessary.
--vehicle	path list			One or more bags of the real vehicle. Necessary.
--json	path		no file	A JSON file with the results.

Shell

python ROS/Tools/check_topic_parity.py \
    --sim /data/sim_bag \
    --vehicle /data/bags/dbw_direct_test_01

check_msg_defs.py

Examines whether the messages of a bag agree with a set of .msg files. The tool reads each message, writes it again with the given definitions and compares the bytes. Use it when you change the release of ds_dbw_msgs. Exit code 0 = all messages agree.

Name	Type	Unit	Default	Description
BAG	path list			Bag folders or .db3 files.
--msgs	path list			The folders of the message packages. Necessary.
--limit	integer		all	The number of messages for each topic.
--quiet	flag		off	Prints only the result line.

Shell

python ROS/Tools/check_msg_defs.py /data/sim_bag \
    --msgs ROS/vendor/ds_dbw_msgs --limit 200

bench_sensor_stream.sh

Measures the frame rate of the packaged game in four configurations. The configurations are: no sensors, the sensor stream without a client, the stream with the bridge, and the sensor recorder. The script starts the game four times. It stops when a game is already in operation.

Name	Type	Unit	Default	Description
out_dir	path		ROS/log/bench_sensor_stream	The folder of the results (summary.json).
seconds	number	s	40	The time of each measurement.
CONFIGS	variable		base stream ros files	The configurations to run.

Shell

source ROS/Env/setup_env.sh
ROS/Tools/bench_sensor_stream.sh /tmp/bench 40

build_lab_follower.sh

Copies the lab package polaris_qgis_follower into ROS/lab_ws/src and builds it there without changes. The folder ROS/lab_ws is not in the repository. The script needs the fence.

Name	Type	Unit	Default	Description
src_dir	path		$POLARIS_EXTRACT/refs/pc/ros2_ws/src/polaris_qgis_follower	The source folder of the lab package.

Shell

source ROS/Env/setup_env.sh
ROS/Tools/build_lab_follower.sh
source ROS/lab_ws/install/local_setup.bash

export_polaris_meshes.py

A Blender script. It writes the visual meshes of the Polaris (meshes/polaris/*.stl) and the file urdf/polaris_visual.xacro for acres_description. Run it again only when the Polaris model changes.

Shell

blender -b Acres/Raw/farm-equipment/polaris/graphite/polaris_graphite.blend \
    --python ROS/Tools/export_polaris_meshes.py -- ROS/acres_description