UART Examples (Blocking API)
============================

Overview
~~~~~~~~

The blocking UART examples are available for both C and C++:

- C: ``examples/blocking_api/uart/c/``
- C++: ``examples/blocking_api/uart/cpp/``

These examples are intended for both **Supernova** and **Pulsar** USB host adapters.

Hardware Setup
~~~~~~~~~~~~~~

Required hardware:

1. One Binho **Supernova** or **Pulsar**
2. One Binho **Breakout Board**

Required wiring:

- Interconnect **TX** and **RX** on the breakout board to close the hardware loopback path.
- Otherwise, connect another UART device to the breakout board for a real-world test. In this case, the user is in charge of configuring the external device to match the UART settings used in the example.

What The UART Examples Do
~~~~~~~~~~~~~~~~~~~~~~~~~

1. Create the SDK instance/handle.
2. Register a UART receive notification callback at the beginning of the program.
3. Connect to the adapter and retrieve device information.
4. Initialize UART with ``115200-8N1`` and send ``Hello, world!``.
5. Receive loopback data through the registered callback.
6. Reconfigure UART to ``9600-8N1`` and send the same message again.
7. Receive loopback data again through the callback.

Notification Callback Requirement
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

UART receive data is delivered through asynchronous notifications.  
For this reason, the client application must register a callback before UART
traffic begins:

- C API: ``CosmicSDK_onNotification``, then parse UART notifications with
  ``CosmicSDK_notificationAsUartRx``.
- C++ API: ``CosmicSDK::onNotification`` and parse using
  ``notification.uartRx()``.

Synchronization Mechanism
~~~~~~~~~~~~~~~~~~~~~~~~~

The examples use callback-driven synchronization instead of fixed sleeps.
After each UART transmission, the main flow waits until the callback signals
that loopback data has been received (with a timeout to avoid blocking forever).

- C example: platform synchronization primitives (Windows condition variable or
  POSIX ``pthread`` condition variable) plus a notification counter.
- C++ example: ``std::mutex`` + ``std::condition_variable`` plus a notification
  counter.

Build and Run (UART C/C++)
~~~~~~~~~~~~~~~~~~~~~~~~~~

UART example directories build binaries with the following names:

- C (``examples/blocking_api/uart/c/``):
    - ``example_c_dynamic``
    - ``example_c_static``
- C++ (``examples/blocking_api/uart/cpp/``):
    - ``example_cpp_dynamic``
    - ``example_cpp_static``

See also:

- C API UART reference: :doc:`../../api/c/uart`
- C++ blocking UART reference: :doc:`../../api/cpp_blocking/uart`