Getting started
===============

The fastest way to see the whole stack working is ``motion_planning_example``:
one ``ros2 launch`` brings up a Gazebo Harmonic simulation of a single-arm
workcell plus every node needed to plan a motion and execute it.

It is the only runnable end-to-end demo, and it exercises the same code path a
real application uses — including the real ``motion_control_ros`` driver, which
talks to the simulated arm over the same TCP protocol it uses against hardware.

Prerequisites
-------------

- ROS 2 Jazzy
- Gazebo Harmonic — ``gz`` must be on ``PATH``
- ``xacro``, ``rviz2``, ``foxglove_bridge``
- the sibling repositories in the same workspace: ``mesh_models``,
  ``core_interfaces``, ``core_motion_planning``, ``core_motion_control``,
  ``core_modeling``, ``core_plugins``, ``core_logger``

Build
-----

Always from the workspace root, with a mixin and no other flags:

.. code-block:: bash

   cd /path/to/jazzy_sorting_ws
   colcon build --mixin relwithdebug

.. warning::

   Do not use the ``dev`` profile for anything that runs Gazebo. It enables
   coverage, and ``core_plugins`` puts ``--coverage -O0 -g`` directly on the
   plugin *targets* — a target option beats any build type, so no command-line
   flag can produce an optimised ``ArmPlugin`` from ``dev``. The simulator then
   runs far below real time, which changes the behaviour of anything mixing
   wall-clock timing with simulated motion.

Run the demo
------------

.. code-block:: bash

   source /opt/ros/jazzy/setup.bash
   source /path/to/jazzy_sorting_ws/install/setup.bash

   ros2 launch motion_planning_example demo.launch.py

Gazebo opens with the arm at its home pose and RViz shows the workcell as a
marker array. Useful arguments: ``arm_model`` (ships ``fanuc_m710ic50`` and
``yasakawa_gp50``), ``headless``, ``gz_verbosity``.

Command a motion
----------------

In a second sourced terminal:

.. code-block:: bash

   ros2 run motion_planning_example queue_trajectory_simple --x 1.66 --y 0.05 --z 0.97

The script discovers the arm's joints and TF frames, calls
``/compute_motion_plan`` with a pose goal, then ``/robot_enable`` and the
``/queue_trajectory`` action. The arm should move in Gazebo with the RViz markers
following.

.. note::

   On the default M-710iC/50 the arm has no wrist-roll axis, so a fully
   constrained 6-DOF orientation goal is usually unreachable. Start with position
   only and let the orientation default.

Shut down properly
------------------

``ros2 launch`` children do **not** die with the parent. Kill the whole launch
tree after every run — a leftover ``gz sim`` or ``motioncontrolapp`` keeps
holding ports 50240/50241, and the next run fails with ``Failed to accept for
client connection``, which looks like a plugin bug. Check what matches before
killing anything; never blanket-``pkill`` by name.

Where to go next
----------------

- :doc:`../concepts/architecture` — how the layers fit together
- :doc:`../tutorials/build_an_application` — build your own application
- ``motion_planning_example``'s README — the full argument reference, partial
  bring-up, and how to adapt the demo to a different robot