# UART API

This page aggregates all UART-related functions for the C API.

group CosmicSDK UART API

  Constants and APIs related to UART operations.

  Functions

  uint16_t CosmicSDK_UartSetBusVoltage(CosmicSDK_Handle *handle, uint16_t voltage_mV, bool persist)

    Sets the UART bus voltage.

    Warning

    On Supernova and Pulsar host adapters, the UART interface shares the same voltage domain as I2C, SPI and GPIOs. As a result, calling this method to set the UART voltage will also affect the voltage of I2C, SPI and GPIO interfaces. This must be taken into account when more than one interfaces are used simultaneously.

    Parameters:

      - handle – Handle to the CosmicSDK instance

      - voltage_mV – Voltage in millivolts to set the UART interface to. The valid values are 0 mV, and any value in the range 1200 to 3300 mV. The value 0mV deactivates the VTARG pin and turn offs the downstream devices.

      - persist – bool If true, the voltage setting will be persistent across power cycles. This ensures that any DUT connected to the UART interface (e.g. via Pulsar or Supernova) will receive power immediately upon startup, without waiting for the host to issue the voltage set command. If false, the setting will only apply to the current session.

    Returns:

      SUCCESS on success, error code otherwise

  uint16_t CosmicSDK_UartInit(CosmicSDK_Handle *handle, UartBaudRate baudrate, UartHwHandshake hardwareHandshake, UartParity parityMode, UartDataSize dataSize, UartStopBit stopBit)

    Initialize the UART interface.

    This function initializes the UART peripheral and must be called successfully before any other UART-related API is used.

    Note

    - This function must be called exactly once.

    - Calling any UART API before initialization will result in `FW_INTERFACE_NOT_INITIALIZED`.

    - Calling this function more than once will result in `FW_INTERFACE_ALREADY_INITIALIZED`.

    - To modify the UART configuration after initialization, use CosmicSDK_UartSetParameters instead of reinitializing the interface.

    Parameters:

      - handle – Handle to the CosmicSDK instance

      - baudrate – UART baud rate used for both transmission (TX) and reception (RX). See UartBaudRate for supported values.

      - hardwareHandshake – Enables or disables hardware flow control (RTS/CTS), if supported by the underlying hardware. See UartHwHandshake for supported values.

      - parityMode – UART parity configuration. See UartParity for supported values.

      - dataSize – Number of data bits per UART frame. See UartDataSize for supported values.

      - stopBit – Number of stop bits per UART frame. See UartStopBit for supported values.

    Return values:

      - SUCCESS – UART interphase was successfully initialized.

      - FW_INTERFACE_ALREADY_INITIALIZED – The UART interface has already been initialized.

      - FW_INVALID_PARAMETER – One or more configuration parameters are invalid or unsupported.

      - SDK_ERROR_TIMEOUT – The operation timed out.

      - SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

  uint16_t CosmicSDK_UartSetParameters(CosmicSDK_Handle *handle, UartBaudRate baudrate, UartHwHandshake hardwareHandshake, UartParity parityMode, UartDataSize dataSize, UartStopBit stopBit)

    Configure UART peripheral communication parameters.

    This function updates the UART communication parameters after the UART interface has been successfully initialized using CosmicSDK_UartInit. It allows runtime reconfiguration of the UART without requiring a full deinitialization or reinitialization of the peripheral.

    Note

    - This function must only be called after a successful call to CosmicSDK_UartInit.

    - Calling this function before UART initialization will result in FW_INTERFACE_NOT_INITIALIZED.

    Parameters:

      - handle – Handle to the CosmicSDK instance.

      - baudrate – UART baud rate used for both transmission (TX) and reception (RX). See UartBaudRate for supported values.

      - hardwareHandshake – Enables or disables hardware flow control (RTS/CTS), if supported by the underlying hardware. See UartHwHandshake for supported values.

      - parityMode – UART parity configuration. See UartParity for supported values.

      - dataSize – Number of data bits per UART frame. See UartDataSize for supported values.

      - stopBit – Number of stop bits per UART frame. See UartStopBit for supported values.

    Return values:

      - SUCCESS – UART parameters were successfully updated.

      - FW_INTERFACE_NOT_INITIALIZED – The UART interface has not been initialized.

      - FW_INVALID_PARAMETER – One or more configuration parameters are invalid or unsupported.

      - SDK_ERROR_TIMEOUT – The operation timed out.

      - SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.

  uint16_t CosmicSDK_UartSendMessage(CosmicSDK_Handle *handle, uint8_t *inData, uint16_t dataLength)

    Transmit a UART message through the host adapter device.

    Requests the host adapter to send data using the currently active UART configuration (see CosmicSDK_UartInit and CosmicSDK_UartSetParameters).

    Note

    - The UART interface must be successfully initialized with CosmicSDK_UartInit before calling this function.

    - If the UART interface is not initialized, this function returns `FW_INTERFACE_NOT_INITIALIZED`.

    Parameters:

      - handle – Handle to the CosmicSDK instance.

      - inData – Pointer to the buffer containing the bytes to transmit.

      - dataLength – Number of bytes to transmit from `data`.

    Return values:

      - SUCCESS – UART message were successfully sent.

      - FW_INTERFACE_NOT_INITIALIZED – The UART interface has not been initialized.

      - FW_INVALID_PARAMETER – One or more parameters are invalid or unsupported.

      - SDK_ERROR_TIMEOUT – The operation timed out.

      - SDK_ERROR_DISCONNECT – The device was disconnected or became unavailable during the operation.