ROS 2 Concepts for OLO
======================

SDK v2 is a typed control plane over a live ROS 2 system. You do not need to
write an ``rclpy`` or ``rclcpp`` node for every script, but the ROS graph and
its conventions still determine what the SDK can observe and control.

Nodes, topics, services, and actions
------------------------------------

**Nodes** are processes in the ROS graph. **Topics** are typed publish/subscribe
streams such as ``/scan``, ``/odom``, or ``/joint_states``. SDK v2 Core can
inspect topics, publish typed messages, subscribe, read the latest message, and
work with node parameters.


Domains and discovery
---------------------

``ROS_DOMAIN_ID`` isolates DDS discovery. Nodes in different domains do not
normally discover one another. The Appliance uses ``OLO_APL_ROS_DOMAIN_ID`` to
join the intended domain. One Appliance sees only the ROS graph available in
that domain and network environment.

Namespaces organize multiple robots inside a domain. For example, ``robot_1``
and ``robot_2`` can each expose a relative ``joint_states`` topic without
colliding. SDK v2 discovers robot namespaces and uses a robot handle to resolve
relative names:

.. code-block:: python

   with Client() as client:
       robot_1 = client.robot("robot_1")
       robot_2 = client.robot("robot_2")

A leading slash makes a topic absolute; a bare name is relative to the handle's
namespace. If exactly one robot is discoverable, ``client.robot()`` resolves it.
Ambiguous multi-robot graphs require an explicit namespace. The complete rules
are in :doc:`namespaces`.

Frames and transforms
---------------------

ROS TF describes coordinate frames and transforms between them. The Spatial
service provides the complete transform tree, exact lookups, and
namespace-scoped robot frames. On a robot handle, bare frame names such as
``base_link`` are scoped to the robot while global frames such as ``world``,
``map``, and ``odom`` remain global.

MoveIt and Nav2
---------------

Kinematics operations depend on MoveIt, the robot model, controllers, and a
valid transform tree. Navigation operations depend on Nav2, localization,
maps or costmaps as required by the deployment, and the relevant controllers.
The SDK can report that a capability is unavailable, but it does not install or
configure these ROS stacks.

Simulation time
---------------

Simulations commonly publish ``/clock`` and set ``use_sim_time`` on
participating nodes. The Appliance has one runtime ``useSimTime`` setting used
when it brings up Nav2, MoveIt, and exploration components. Mixing wall-clock
and simulation-time nodes can cause stale transforms, timeouts, or goals that
never progress.