C++ and Python API
==================

The primary contract between packages is :doc:`interfaces/index` — messages,
services and actions. Reach for a library API only when you are working inside a
package or the interfaces genuinely cannot express what you need.

Client facades
--------------

Each service layer ships a client that wraps its interfaces. These are the entry
points worth knowing:

.. list-table::
   :header-rows: 1
   :widths: 32 20 48

   * - Client
     - Language
     - Wraps
   * - ``motion_planning_client``
     - C++ / Python
     - ``/compute_motion_plan``, ``/compute_ik``, ``/compute_fk``,
       ``/check_robot_collision``
   * - ``motion_control_client``
     - C++ / Python
     - ``/robot_enable``, ``/queue_trajectory``
   * - ``workcell_description`` client
     - C++
     - workcell model queries, TF lookups

.. warning::

   ``motion_planning_client`` currently exists in three implementations with
   different method sets, and the Python and C++ surfaces have diverged. Check
   which one your package depends on before assuming a method exists.
   Consolidating these is planned; until then the interfaces are the reliable
   contract.

Foundation libraries
--------------------

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - Package
     - Provides
   * - ``core_logger``
     - Logging for the whole stack — see :doc:`../howto/logging`
   * - ``core_types``
     - Shared value types used across package boundaries
   * - ``core_tf``
     - Transform helpers over ``tf2``
   * - ``core_utils``
     - Low-level utilities; the one package permitted to log directly

Error codes
-----------

Planning and control results carry an error code rather than a bare boolean.
``ErrorCodes::ToString`` renders one for a log line. Note that not every non-zero
code is a failure worth a ``WARN``: codes such as ``START_AND_GOAL_STATE_TOO_CLOSE``
are routine outcomes — the arm is already where it was asked to go — and the
error-code logger routes them to ``INFO``.

Generated documentation
-----------------------

Per-repository Doxygen output is published alongside each repository's own
documentation site. This page covers the surfaces you need to *use* the stack;
the generated reference covers everything else.

.. note::

   Doxygen coverage is uneven — roughly 1066 classes across 559 headers, with
   inconsistent comment density. Where the generated docs are thin, the
   interfaces and this site's guides are the better starting point.