Competition APIs

The simulator offers a number of topics to retrieve information and feedback on the competition run, such as run time remaining, current phase, and current score. It also provides 2 important endpoints needed for the identification and intervention phases of the competition: One for streaming live video from the vehicles back to the operator, and another for report target vessels, small objects, and large objects.

ROS Topic	Description	Message type
/clock	Current sim time	rosgraph_msgs/msg/Clock
/mbzirc/run_clock	Count down clock to indicate end of setup phase / run	rosgraph_msgs/msg/Clock
/mbzirc/score	Current score (time elapsed + penalty)	std_msgs/msg/Float32
/mbzirc/phase	Current phase	std_msgs/msg/String
/mbzirc/target/stream/start	Endpoint to stream live video imagery to	sensor_msgs/msg/Image
/mbzirc/target/stream/report	Endpoint for reporting targets	ros_ign_interfaces/msg/StringVec
/mbzirc/target/stream/status	Status of target stream reports	std_msgs/msg/String

Phase

The /mbzirc/phase phase topic provides status on the current phase of the simulation. Current phase is published to this topic at 1Hz. The phases are:

• setup: Initial phase of the competition in which the simulator starts spawning robots in the start gate. The default time allowed for setup is 10 mins and the /mbzirc/run_clock topic outputs the time remaining in this phase.
• started: The run officially starts once the setup time counts down to 0 or when a robot moves for more than 5 meters from its spawn location. The default time for the competition is 60 mins, and the /mbzirc/run_clock topic will now output the time remaining in this phase.
• vessel_id_success: The target vessel has been successfully identified.
• small_object_id_success: The small target object has been successfully identified.
• large_object_id_success: The large target object has been successfully identified.
• small_object_retrieve_success: The small target object has been successfully retrieved.
• large_object_retrieve_success: The large target object has been successfully retrieved.
• finished: Competition ended. All targets have been identified / retrieved. Simulation should now be paused.

Identifying Targets

As per rulebook, the teams should stream live video to the operator who will in turn provide a boolean yes / no response to indicate if identification is successful or not. To simulate this interaction we provide these 3 APIs in simulation:

/mbzirc/target/stream/start

Endpoint for streaming live video images to. The images must come from one of the robots in simulation as we will verify the frame_id field of the image message for validating targets reports. The video stream will be transmitted over the inter-robot communication channel so make sure you are sending images within a reasonable range from the base station located next to the start gate, otherwise image data will start dropping. One strategy is to relay the image data to another robot in the field that is closer to the base station and let it be the one sending the live video stream.

For testing this API, here is an example of republishing the image data from a quadrotor camera to this API:

ros2 run image_transport republish raw --ros-args --remap in:=/quadrotor_1/slot3/optical/image_raw --remap out:=/mbzirc/target/stream/start

The above command subscribes to the images from the downward looking camera (in slot3, see UAV and USV Payload Configurations) on a quadrotor and republishes them to the /mbzirc/target/stream/start topic.

There is a ROS2 C++ example code showing how to subscribe to an image topic, optionally updates its frame_id message field (if it has changed due to image processing), and republishes the image data to the base station.

• /mbzirc/target/stream/report
• /mbzirc/target/stream/status

Stream status

• stream_started: Video stream successfully received on the /mbzirc/target/stream/start
• stream_start_failed: Video stream received on the /mbzirc/target/stream/start but failed to validate images. It is likely that the image's frame_id field is incorrect.
• target_reported_run_not_active: Target identification report received on the /mbzirc/target/stream/report topic but the run has not officially started yet.
• vessel_id_success: The target vessel has been successfully identified.
• small_object_id_success: The small target object has been successfully identified.
• large_object_id_success: The large target object has been successfully identified.

Ignition Topics and Services

You may notice instructions that reference Ignition topics or services in the tutorials. These are meant for use during local development and testing. These Ignition topics and services will not be available during the competition run.