CDC Modes Getting Started
=========================

Overview
--------
The CDC interface presents a USB virtual COM port. The device can run one of
five CDC modes. Choose the mode that matches the protocol or workflow you want
to connect to on the host.

The CDC mode setting is stored in flash, so it is persistent across power
cycles.

.. note::
   CDC mode support is device-specific. Supernova supports UART passthrough,
   Terminal shell, and Nova compat. Pulsar supports UART passthrough,
   Nova compat, RS-485 bridge, and CAN-FD bridge.

Configuring CDC Modes (Supernova/Pulsar)
----------------------------------------
Use the ``UsbConfig`` struct with ``getUsbConfig()`` to read the current CDC
mode and ``setUsbConfig()`` to store a new one. On Supernova and Pulsar, the
new setting is saved immediately but only takes effect after a device reset.

Supernova supports ``USB_CDC_UART_PASSTHROUGH``, ``USB_CDC_TERMINAL``, and
``USB_CDC_NOVA_COMPAT``. Pulsar supports ``USB_CDC_UART_PASSTHROUGH``,
``USB_CDC_NOVA_COMPAT``, ``USB_CDC_RS485``, and ``USB_CDC_CANFD``.

.. code-block:: cpp

  #include "CosmicSDK.hpp"
  #include "definitions.h"

  CosmicSDK sdk;
  UsbConfig cfg = {};

  // Read current USB CDC mode.
  if (sdk.getUsbConfig(cfg) == SUCCESS) {
    // cfg.cdc_mode now holds the current CDC mode.
  }

  // Switch to a new CDC mode (example: Pulsar RS-485 bridge).
  cfg.cdc_enabled = USB_CDC_ENABLED;
  cfg.cdc_mode = USB_CDC_RS485;
  cfg.webusb_enabled = USB_WEBUSB_NO_CHANGE; // keep current WebUSB state
  if (sdk.setUsbConfig(cfg) == SUCCESS) {
    // Reset the device to apply the new CDC mode.
  }

Modes And Use Cases
-------------------
UART passthrough
  Transparent USB-to-UART bridge. The CDC stream is passed directly to the
  UART lines with no interpretation. Use this for raw serial access to a
  target MCU, modem, or any device that expects a standard UART connection.

Terminal shell
  Interactive I3C/I2C/GPIO serial shell (the I3CBlaster emulator), available on
  Supernova only. Use this to drive I3C, I2C, and GPIO operations from a serial
  terminal without writing host code against the SDK. Note that I2C here is not a
  dedicated I2C bus: it is legacy I2C running over the I3C peripheral (I2C-over-I3C)
  on the I3C port, so it shares those lines rather than the standalone I2C bus.

Nova compat
  Binho Nova text protocol compatibility. The CDC stream speaks the Binho Nova
  text command protocol, exposing the I2C master, SPI master, GPIO, and 1-Wire
  master (Pulsar only, via the onboard DS2483) protocol families. Use this when
  you need host tools or scripts written for the Binho Nova command set, or to
  access 1-Wire on Pulsar.

RS-485 bridge
  RS-485 half-duplex bridge implemented with the SP3485CN transceiver, available
  on Pulsar only. Bus direction (driver-enable) timing is handled by the device.
  Use this for multi-drop industrial buses (e.g., Modbus RTU) that require
  half-duplex signaling.

CAN-FD bridge
  CAN-FD SLCAN bridge implemented with the TJA1044GT transceiver, available on
  Pulsar only. The bridge is compatible with the SLCAN protocol and the
  ``python-can`` library. Use this as a USB-to-CAN-FD adapter for bus monitoring
  or injection.

Switching Modes Safely
----------------------
Before changing CDC modes in firmware, call ``uartDeinit()`` to release the
UART and avoid leaving the previous mode's configuration active.

After selecting a new mode, the device will remember it in flash. Reset the
device to apply the new CDC mode.