# 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: UART API

- C++ blocking UART reference: UART API