docs/ros2-guide

ROS 2 Guide

A deep dive into how Artemis integrates with ROS 2 — topics, services, QoS profiles, node lifecycle, and multi-robot configuration.

Supported ROS 2 Distributions

Distribution	Support	Notes
Jazzy Jalisco	✔ Full	Recommended
Humble Hawksbill	✔ Full	LTS — broadly supported
Iron Irwini	✔ Full
Galactic	⚠ Partial	EOL — upgrade recommended
Foxy	✗ Unsupported	EOL

Topics

When you deploy a model to a robot, the Artemis agent starts a managed ROS 2 node that subscribes to your input topic and publishes inference results on the output topic.

Topic	Direction	Message Type
/kairo/input	Subscribes	sensor_msgs/msg/Image (configurable)
/kairo/inference	Publishes	kairo_msgs/msg/Inference
/kairo/status	Publishes	kairo_msgs/msg/AgentStatus
/kairo/cmd/reload	Subscribes	std_msgs/msg/String

Override the default input topic at deploy time:

bash

kairo deploy push \
  --model mdl_abc123 \
  --robot rob_a1b2c3d4 \
  --input-topic /camera/rgb/image_raw \
  --output-topic /kairo/inference

QoS Profiles

Artemis uses Reliable delivery with Transient Local durability by default. For high-frequency sensor topics, switch to a best-effort profile to reduce latency:

yaml

# kairo.yaml
qos:
  input:
    reliability: best_effort
    durability: volatile
    history: keep_last
    depth: 10
  output:
    reliability: reliable
    durability: transient_local

⚠

Using best_effort on the output topic means subscribers may miss inference messages if they are not running when a message is published. Use reliable for safety-critical outputs.

Node Lifecycle

The Artemis agent implements the ROS 2 Managed Node lifecycle. This gives you fine-grained control over when the model is active:

Unconfigured

Agent is running, model is not loaded. Waiting for configuration.

Inactive

Model is loaded into memory but not processing inputs.

Active

Model is running and publishing inference results.

Finalized

Node has been cleanly shut down. Resources are released.

Transition between states using the standard ROS 2 lifecycle CLI:

bash

# Activate the Artemis node
ros2 lifecycle set /kairo_agent activate

# Deactivate (pause inference without unloading model)
ros2 lifecycle set /kairo_agent deactivate

Multi-Robot Configuration

For fleets with multiple robots sharing the same ROS 2 domain, use namespacing to avoid topic collisions:

bash

kairo deploy push \
  --model mdl_abc123 \
  --robot rob_a1b2c3d4 \
  --namespace /robot_01

# Robot 01 publishes on: /robot_01/kairo/inference
# Robot 02 publishes on: /robot_02/kairo/inference

✦

For isolated fleets (different physical networks), use separate ROS 2 Domain IDs and separate Artemis workspaces. Each workspace has its own fleet dashboard view.

Custom Message Types

Artemis supports custom ROS 2 message types for inference input and output. Register your custom message package with the Artemis agent:

bash

kairo config set-messages \
  --robot rob_a1b2c3d4 \
  --input-type my_pkg/msg/SensorArray \
  --output-type my_pkg/msg/ControlCommand

Your message package must be installed and sourced on the robot host before the agent starts.

Was this page helpful?