.. _interfaces_cpp_api:
.. _built_in_modules_cpp_api_wrapper:

=====================
Wrapping Rogue In C++
=====================

For embedding or controlling a PyRogue tree from a C++ application, Rogue
provides ``rogue::interfaces::api::Bsp``. This wrapper sits in the built-in
interfaces section because it is an integration layer around a running PyRogue
tree rather than part of the tree model itself.

``Bsp`` wraps a PyRogue node or ``Root`` object and provides helper methods for
node traversal, command execution, variable access, and root-level listeners.

Creating A Root Wrapper
-----------------------

``Bsp`` can construct and start a PyRogue root directly from Python module/class
names:

.. code-block:: cpp

   #include "rogue/interfaces/api/Bsp.h"

   // Imports pyrogue.examples and constructs ExampleRoot().
   rogue::interfaces::api::Bsp bsp("pyrogue.examples", "ExampleRoot");

If constructed this way, the root is started in the constructor and stopped in
the wrapper destructor.

This is the common pattern when a C++ process needs to host the PyRogue
application directly instead of connecting to it through a remote client
interface.

Node Traversal And Variable Access
----------------------------------

Use ``operator[]`` for hierarchical traversal and ``getNode()`` for full-path
lookup:

.. code-block:: cpp

   // Read variable from local cached value (no forced hardware read).
   std::string localTime = bsp["LocalTime"].get();

   // Write variable and then force readback.
   bsp["AxiVersion"]["ScratchPad"].setWrite("0x1111");
   std::string scratch = bsp["AxiVersion"]["ScratchPad"].readGet();

   // Full-path lookup returns a shared pointer wrapper.
   auto node = bsp.getNode("ExampleRoot.AxiVersion.ScratchPad");
   std::string scratch2 = node->get();

Commands
--------

Command nodes are invoked through ``operator()`` or ``execute()``:

.. code-block:: cpp

   // Execute commands without arguments.
   bsp["WriteAll"]();
   bsp["ReadAll"]();

   // Execute command with argument string.
   std::string yaml = bsp["GetYamlConfig"]("True");

Variable Listeners (Root Only)
------------------------------

Variable listeners can be attached only on a root wrapper:

.. code-block:: cpp

   void varListener(std::string path, std::string value) {
       // Called for each variable update pushed to this listener.
       printf("Var Listener: %s = %s\n", path.c_str(), value.c_str());
   }

   void varDone() {
       // Called when the current listener batch is complete.
       printf("Var Done\n");
   }

   bsp.addVarListener(&varListener, &varDone);

What To Explore Next
====================

- Built-in interface overview: :doc:`/built_in_modules/interfaces/index`
- Version checks and compatibility guards: :doc:`/built_in_modules/interfaces/version`
- SQL-backed tree logging: :doc:`/built_in_modules/interfaces/sql`

Related Topics
==============

- PyRogue tree structure and lifecycle: :doc:`/pyrogue_tree/index`
- Core Root/Device/Variable behavior: :doc:`/pyrogue_tree/core/index`
- Remote client/server access patterns: :doc:`/pyrogue_tree/client_interfaces/index`

API Reference
=============

- C++: :doc:`/api/cpp/interfaces/api/bsp`